Docs for language models
The menu at the top of each page copies the page as Markdown, opens it as Markdown, opens it in
ChatGPT or Claude with the page as context, or copies the address of the docs MCP server.
Connect the docs MCP server
The docs have a hosted Model Context Protocol (MCP) server athttps://lean.mintlify.site/mcp. An
assistant connected to it can search these docs and read their pages while it works. It serves only
the public docs: it can’t call the Lean API or see your account, and it needs no key.
Run the Lean MCP server
The Lean MCP server is different from the docs MCP server: it calls the Lean API with your API key, so an assistant connected to it can read markets, books, candles, orders, positions, profit and loss, risk, stop losses, deposits, withdrawals and transfers for your account. It runs on your machine over stdio with Bun, and the key stays in its environment, so the key is never sent to the model. The server is thesdks/mcp package of the
Lean SDKs, started with bun sdks/mcp/src/index.ts.
It is read only by default. These tools are always available:
list_markets, get_market,
quote_market, get_market_book, get_market_trades, get_market_candles, get_prices,
list_orders, get_order, list_fills, get_positions, get_balances, get_account_config,
get_pnl, get_pnl_history, get_risk, list_stop_losses, get_stop_loss,
list_limit_chases, get_limit_chase, get_deposit_addresses, get_deposit_assets, list_withdrawals, get_withdrawal,
quote_transfer, list_transfers and get_transfer. Any tool that takes a market ID also takes
a venue’s own ID for it, such as a Polymarket token ID, a Kalshi market ticker or a ticker with a
pm:, pmus: or hl: prefix. The read and trading tools cover Kalshi, Polymarket, Polymarket US
and Hyperliquid. Deposits, transfers and withdrawals cover Polymarket and Hyperliquid only.
Tools that change anything need two things: the server starts with --enable-trading, and
the key has the scope the API checks for that tool. Otherwise the assistant isn’t offered them at
all. With the flag and a Read only key, the server says so when it starts and stays read only.
create_order and preview_order take every order type the API takes: limit or market, by
quantity or by dollar amount, good till canceled, immediate or cancel, fill or kill, or good till
a time, and post only.
pause_trading and lower_limits let an assistant stop its own trading or tighten its own key.
Neither can be undone through the API: only the Lean app resumes trading or raises a limit.
Start with a test key, so orders are simulated and no money moves, and give the key tight limits.
Every tool answers with the API response, including livemode, and an API error comes back with
its code, message and request ID. A tool refuses any argument it does not define, so a misspelled
filter is an error, not silently ignored.
Use the OpenAPI spec
The OpenAPI spec (OpenAPI 3.0) lists every endpoint with its parameters, request and response schemas and error shapes. Its server is{baseUrl}/v1, and
baseUrl defaults to https://api.lean.xyz, the same value as LEAN_API_URL in these guides.
/api-keys operations:
they take the session token of a person signed in to Lean, not an API key. When the model writes
requests itself, attach the spec, or the schemas for the calls it makes, so its bodies match.
Generate a client. For TypeScript and Rust, the TypeScript SDK and the
Rust SDK are already generated from the spec. Any OpenAPI 3.0 generator works for
other languages, for example:
Authorization: Bearer <key>, the spec’s apiKey scheme. The spec’s
info.version is the release named in the changelog. Download the spec again when
the changelog lists a new release. See Versioning.
A system prompt for a trading agent
Start from this prompt for an agent that trades through/v1 with a test key. Give the agent the
key through its environment or a tool, never in the prompt text, so the key isn’t sent to the model
provider or kept in logs.
Safety checklist
- Start in test mode. A test key simulates orders and fills with simulated balances, and
responses carry
livemode: false. Move to a live key only after the agent behaves well on a test key. See Go live. - Preview before placing. Preview an order shows the
legs, prices, cost and
would_submitwithout placing anything. It is the natural approval step. See Preview. - Use idempotency keys. A
client_order_idsaved before sending makes every retry safe. The same ID never places a second order. See Idempotency. - Set tight key limits. Give the agent’s key a per order and daily limit no higher than it needs. Lean refuses any order above them before it reaches a venue. A research agent gets a Read only key, which can preview but not place orders. See Authentication and Lower key limits.
- Keep a way to stop it. Pause trading stops new orders for a key or the whole trading account in one call, and only the Lean dashboard resumes. Run the pause from a monitor outside the agent too, and revoke a key from Lean at any time.
An AI agent that trades within a budget
A research agent on a read only key proposes trades, and an execution key places them after
approval.
Quickstart
From a new key to a filled test order in one call.