Set Up Finlet

Everything you need to connect your AI agent to Finlet and run your first simulated trade.

Prefer your terminal? Run finlet manual quickstart for the binary-portable, agent-readable version of these four steps. The CLI manual is the source of truth — this page mirrors it.

What is Finlet?

Finlet is an agentic trading evaluation harness for testing AI trading strategies in simulated markets with real historical data. Your agent replays any historical market period, seeing only data available at that point in time — prices, news, and fundamentals. No look-ahead bias, no real money at risk.

Connect via the finlet CLI, MCP (Model Context Protocol), or the REST API directly. Every call and decision is logged in a full reasoning trace for post-hoc analysis.

Paper trading only Real historical data No credit card required Free tier available

Getting Started with Finlet

Follow these four steps to go from zero to your first simulated trade. Your AI agent does the work; this page shows the canonical MCP wire-up. Expand the fallback sections only when your environment cannot run the primary stdio flow.

Install Finlet

Open your terminal and install Finlet using pip. You need Python 3.12 or newer. The default install ships the CLI, the manual, and the finlet mcp serve stdio bridge your agent host will spawn.

Terminal

pip install finlet

Don't have Python? Download it from python.org. On macOS you can also use brew install python.

Prefer no install? Use the REST API directly

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

cURL

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

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

Self-host (optional)

Most users don't need this — the default stdio bridge proxies to finlet.dev. Self-hosted operators who run their own API/auth/database stack can install the server extra and start the local FastMCP server with finlet mcp serve --self-host:

Terminal

pip install 'finlet[server]'

Authenticate

Run finlet auth login once. The CLI opens your browser, completes the OAuth flow, and writes the Bearer credential to ~/.finlet/credentials with mode 0600. The stdio bridge reads that file and proxies to hosted /mcp when your agent host starts it.

Terminal

finlet auth login

Create an account or API key without the browser flow

The website signup is the normal path. CI workers and other non-interactive environments can register through REST and use an api_key fallback.

cURL

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

Response includes an api_key. Treat it like a password and prefer OAuth whenever a browser is available.

Wire MCP into your agent host

Add Finlet as an MCP stdio server. This is the canonical v2 config: no environment variables, no headers, no URL. The subprocess reads the OAuth credential from ~/.finlet/credentials and forwards to hosted /mcp.

JSON

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

Codex shortcut: run codex mcp add finlet -- finlet mcp serve. Other MCP clients use the JSON block above.

Hosted HTTP fallback

Use this only for clients that explicitly support hosted MCP over HTTP and can pass a Bearer token header.

JSON

{
  "mcpServers": {
    "finlet": {
      "url": "https://finlet.dev/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <oauth_jwt>"
      }
    }
  }
}

Headless / CI fallback (api_key)

Use this only when the runner cannot complete browser OAuth. The api_key is passed to the subprocess environment.

JSON

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

Available MCP tools

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

Dialog with your agent

Open your agent host and ask for the full simulation flow in natural language. The agent calls create_session, submit_order, and get_portfolio through MCP, then reports back.

Ask your agent

Create a session named 'my-first-sim' starting 2024-01-02 with $100,000
capital and tickers AAPL, MSFT, GOOGL. Then place a market BUY order
for 10 shares of AAPL and show me the portfolio.

You're set up. The simulation uses real historical data, starts with a frozen clock, and filters every response through the Date Ceiling Enforcer.

REST fallback for non-MCP frameworks

Use REST when your framework does not speak MCP. Session creation returns a session_id that your HTTP client passes to later endpoints.

cURL

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-02", "initial_capital": 100000, "universe": ["AAPL", "GOOGL", "MSFT"]}'

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".