Set Up Finlet

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

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 six steps to go from zero to your first simulated trade. The main flow uses the finlet CLI — the fastest path from install to trade. Each step has an optional Raw REST API section you can expand if you prefer curl or are building your own HTTP client.

Install the Finlet CLI

Open your terminal and install Finlet using pip (Python's package manager). You need Python 3.12 or newer. The default install ships everything the CLI and MCP client need to talk to the hosted Finlet service at https://finlet.dev.

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 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:

Terminal

pip install 'finlet[server]'

Create your account

Register a free account — no credit card required. The fastest way is to sign up through the website. Once signed in, create an API key from the dashboard or use the REST API below to register and receive your key in one step.

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

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 your API key: {"api_key": "your_api_key_here"}.

Save your API key

Set your API key as an environment variable so Finlet authenticates your requests automatically:

Terminal

export FINLET_API_KEY=your_api_key_here

Important: Treat your API key like a password. Add the export line to your shell profile (~/.zshrc, ~/.bashrc) so it persists across sessions.

Create a simulation session

A session is a simulation environment. You pick a start date, starting capital, and which stocks to trade. The simulation replays that market period so your agent can make decisions based on real historical data.

Terminal

finlet session create --name "my-first-sim" --start 2024-01-01 --capital 100000 --universe "AAPL,GOOGL,MSFT"

What this means: Start with $100,000 virtual dollars on January 1, 2024, trading Apple (AAPL), Google (GOOGL), and Microsoft (MSFT). The response includes the session_id you'll use for all subsequent calls.

Create a session via the REST API instead

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

Returns the same session_id as the CLI command.

Submit a trade via the REST API

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

cURL

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

Connect your AI agent

If your agent supports MCP (Claude Desktop, Claude Code, or any MCP-compatible client), add this configuration. The finlet mcp command starts the MCP server over stdio and exposes Finlet's trading tools directly to your agent.

JSON

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

Note: Replace YOUR_API_KEY with the key from Step 2. If your agent doesn't support MCP, it can call the REST API endpoints directly — see the collapsible sections in the steps above and below.

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

Run your first trade

Your agent can now get market data, submit orders, and check portfolio state. Here's an example trading flow using the REST API — replace {session_id} with the ID returned in Step 4.

cURL

# Get current price for AAPL
curl "https://finlet.dev/v1/sessions/{session_id}/market/price?ticker=AAPL" \
  -H "Authorization: Bearer $FINLET_API_KEY"

# Buy 10 shares of AAPL
curl -X POST "https://finlet.dev/v1/sessions/{session_id}/trade/order" \
  -H "Authorization: Bearer $FINLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL", "side": "buy", "quantity": 10}'

# Check your portfolio
curl "https://finlet.dev/v1/sessions/{session_id}/portfolio" \
  -H "Authorization: Bearer $FINLET_API_KEY"

You're set up! Your agent can now trade in simulated markets using real historical data. Explore the MCP tools in Step 5 to build your strategy with news search, fundamentals, and time-advance controls.

Expected responses and error handling

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