Set Up Finlet

Finlet's REST API works with any HTTP client — no Python install required. Start by verifying the API is reachable:

curl https://finlet.dev/v1/health

Expected response: {"status": "ok"}

Most users don't need this — the cloud at finlet.dev hosts everything. Self-hosted operators who want to run their own API server can install the server extra, which pulls the additional FastAPI / database stack:

pip install 'finlet[server]'

If you'd rather register programmatically, POST to the auth endpoint:

curl -X POST https://finlet.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Response includes your API key: {"api_key": "your_api_key_here"}.

If you can't run finlet auth login (CI workers, eval rigs, anything without a browser), export your api_key as an environment variable. The REST API accepts it on every route, and the finlet mcp serve stdio bridge translates it to OAuth Bearer internally before dispatching to the hosted service.

export FINLET_API_KEY=your_api_key_here

Treat your api_key like a password. Add the export line to your shell profile (~/.zshrc, ~/.bashrc) so it persists across sessions. See finlet manual auth-model for the full credential reference.

curl -X POST https://finlet.dev/v1/sessions \
  -H "Authorization: Bearer $FINLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-sim", "start_time": "2024-01-01", "initial_capital": 100000, "universe": ["AAPL", "GOOGL", "MSFT"]}'

Returns the same session_id as the CLI command.

Once you have a session_id (exported as $SESSION_ID), submit a market buy order:

# Submit a market buy order against a session
curl -X POST https://finlet.dev/v1/sessions/$SESSION_ID/trade/order \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ticker":"AAPL","side":"BUY","quantity":1,"order_type":"MARKET"}'

From the CLI: finlet order --session $SID --ticker AAPL --side BUY --quantity 1.

Use this when the host can't run finlet auth login (CI workers, eval rigs). The stdio bridge translates the api_key to OAuth internally; the agent still sees the same tools and the same data. The MCP HTTP surface at /mcp does not accept the api_key form — stdio is the only path that does.

{
  "mcpServers": {
    "finlet": {
      "command": "finlet",
      "args": ["mcp", "serve"],
      "env": {
        "FINLET_API_KEY": "your_api_key_here"
      }
    }
  }
}

Once connected, your agent can call any of these MCP tools:

• create_session Create a new simulation session
• get_price_data Historical OHLCV price data
• submit_order Submit buy/sell orders
• advance_time Advance the simulation clock
• get_portfolio Current portfolio state
• get_trace Full reasoning trace
• search_news Search news articles
• get_fundamentals Company fundamentals

Price endpoint returns OHLCV data filtered to the session's current simulation time — no future data leaks through the date ceiling enforcer.

Order endpoint returns the filled order with execution price and timestamp. Orders submitted outside market hours queue as PENDING until the next trading session. Insufficient cash returns 400 with a specific actionable message (e.g., "Insufficient cash: need $18,450.00, have $12,000.00").

Portfolio endpoint returns cash, positions (with average entry price and current market value), and aggregate P&L.

Rate limits are reported in response headers. If you exceed them, you'll get a 429 with exact reset time — for example: "Finnhub rate limit exceeded: 0/60 calls remaining, resets in 42 seconds".