Skip to main content
These docs are available as plain Markdown, as one file for language models and through a hosted MCP server, and the OpenAPI spec describes every endpoint. Give them to a coding assistant or an agent so it works from the real API, then start it on a test key.

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 at https://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.
Any other client that supports remote MCP servers over HTTP takes the same address.

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 the sdks/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.
The assistant should still preview every order and wait for your approval before it places one. The system prompt and safety checklist below apply to it too.

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.
Give it to an agent. Many agent frameworks turn OpenAPI operations into tools. Load only the operations the agent needs. A research agent needs the market reads and Preview an order. Leave out the /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:
Send the key as 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_submit without placing anything. It is the natural approval step. See Preview.
  • Use idempotency keys. A client_order_id saved 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.