# Lean API - [Lean API v0.1](https://docs.lean.xyz/index.md): List canonical sports markets, quote them, place orders and reconcile, without naming a venue. - [Quickstart](https://docs.lean.xyz/quickstart.md): From a new key to a filled test order in one call. - [TypeScript SDK](https://docs.lean.xyz/typescript-sdk.md): Call the Lean API from TypeScript, with a typed method for every endpoint. - [Rust SDK](https://docs.lean.xyz/rust-sdk.md): Call the Lean API from Rust, with a typed async method for every endpoint. - [Test mode and live mode](https://docs.lean.xyz/test-mode.md): Build against simulated orders with a test key, then switch to a live key to trade for real. - [Authentication](https://docs.lean.xyz/authentication.md): API keys, scopes, spending limits and rate limits. - [Build with AI](https://docs.lean.xyz/build-with-ai.md): Give a coding assistant or an AI agent these docs, the OpenAPI spec and the Lean MCP server, then let it trade safely on a test key. - [Venues](https://docs.lean.xyz/venues.md): What the API supports on Kalshi, Polymarket, Polymarket US and Hyperliquid. - [Markets and IDs](https://docs.lean.xyz/markets.md): Fixtures, propositions, outcomes, signed lines and market IDs. - [Preview](https://docs.lean.xyz/preview.md): Preview an order without placing it: where it would go, what it would cost, and whether it would be refused. - [Orders and idempotency](https://docs.lean.xyz/orders.md): Place, retry, cancel and reconcile orders safely. - [Stop losses and take profits](https://docs.lean.xyz/stop-losses.md): Sell shares you hold once the market moves to a price you choose. - [Limit chases](https://docs.lean.xyz/limit-chases.md): Rest a limit order near the best price and let Lean move it as the book moves. - [Order statuses](https://docs.lean.xyz/statuses.md): What each order status means and which ones are final. - [Streaming](https://docs.lean.xyz/streaming.md): Follow orders, positions, balances and market books over one WebSocket. - [Errors](https://docs.lean.xyz/errors.md): Error codes, venue codes and what to do about each. - [Funding](https://docs.lean.xyz/funding.md): How money reaches each venue, and the one deposit route to avoid. - [Transfers](https://docs.lean.xyz/transfers.md): Move cash between your account's Polymarket and Hyperliquid balances. - [Advanced: self-signed routed orders](https://docs.lean.xyz/routed-orders.md): Sign the payment for a cross-venue buy yourself, in two calls. - [Versioning](https://docs.lean.xyz/versioning.md): What can change inside /v1, and how breaking changes are announced. - [Changelog](https://docs.lean.xyz/changelog.md): Every Lean API release, newest first. - [Use cases](https://docs.lean.xyz/use-cases/index.md): What teams build with the Lean API, and the exact calls behind each one. - [Best price execution across venues](https://docs.lean.xyz/use-cases/best-price-execution.md): One order, filled at the best combined price across Polymarket and Hyperliquid. - [Model driven trading with hard limits](https://docs.lean.xyz/use-cases/model-driven-trading.md): A bot that turns model edge into orders, with spending caps the API enforces. - [An AI agent that trades within a budget](https://docs.lean.xyz/use-cases/ai-agent-trading.md): A research agent proposes trades on a read only key; an execution key places them after approval. - [Hedging sportsbook exposure](https://docs.lean.xyz/use-cases/hedging-exposure.md): Buy the other side on prediction market liquidity when liability crosses a threshold. - [Price monitoring and alerts](https://docs.lean.xyz/use-cases/price-monitoring.md): Dashboards and alerts on a read only key, with no trading permission. - [Funding and treasury automation](https://docs.lean.xyz/use-cases/funding-automation.md): Find deposit assets and addresses, then watch balances. - [List markets](https://docs.lean.xyz/api-reference/markets/list-markets.md): Canonical sports markets, each with the Kalshi, Polymarket, Polymarket US and Hyperliquid legs that trade the same outcome. Filter by league, sport, status, start time or text, or look up the markets of one venue symbol. Pass `next_cursor` back as `cursor` for the next page. - [Get a market](https://docs.lean.xyz/api-reference/markets/retrieve-market.md): One market by its id, with each venue leg and how that venue resolves it. A market id keeps resolving after its fixture leaves the default list window. A venue symbol that names one market, such as a Polymarket token id or a Hyperliquid book coin, returns that market under its market id. - [Quote a market](https://docs.lean.xyz/api-reference/markets/quote-market.md): The best price to buy a quantity across venues right now, or to sell it from the shares the account holds, with the venue legs that would fill it. A venue symbol is quoted on the one listing it names, which is all an order naming it trades. Nothing is placed or reserved, and books can move before yo… - [Get a market orderbook](https://docs.lean.xyz/api-reference/markets/retrieve-market-book.md): Resting bids and asks for the market on each venue, and the same levels merged across venues. Pass `venue` to read one venue only; a venue symbol reads only the listing it names. A venue whose book could not be read is listed in `unavailable`. - [Get recent trades](https://docs.lean.xyz/api-reference/markets/list-market-trades.md): The latest trades on each venue leg of the market, newest first. Pass `venue` to read one venue only; a venue symbol reads only the listing it names. Pass the `next_cursor` of a page as `cursor` to read older trades. - [Get price candles](https://docs.lean.xyz/api-reference/markets/get-market-candles.md): Open, high, low and close prices and volume per interval for each venue leg of the market, oldest first. Prices are for the side the leg buys. A request covers at most 1000 intervals. Pass `venue` to read one venue only. - [Get prices](https://docs.lean.xyz/api-reference/markets/list-prices.md): Best bid and ask with the quantity resting at each, mid and last trade for up to 25 markets in one call, across venues and per venue. Ids that match no market are returned in `not_found`. - [Preview an order](https://docs.lean.xyz/api-reference/orders/preview-order.md): Runs the same checks as POST /v1/orders on the same body and returns what it would do: the venue legs, the expected average price, the route a buy would take and whether the order would be refused before reaching a venue. Nothing is placed or reserved. - [Preview several orders](https://docs.lean.xyz/api-reference/orders/preview-orders-batch.md): Previews up to 25 order bodies in one call, each exactly as POST /v1/orders/preview previews it, and runs them at once, so a batch takes about as long as its slowest preview. Each body is previewed on its own: the batch does not add the notional of one body to another's limit checks. One body that c… - [Create an order](https://docs.lean.xyz/api-reference/orders/create-order.md): The default way to buy across venues, in one call. Lean places the order on the venues that can fill it. A buy the account cannot pay for on those venues is bought through a route across venues instead when routing is on and the key has the route scope: Lean moves the money from the funding venue an… - [List orders](https://docs.lean.xyz/api-reference/orders/list-orders.md): Orders placed through the API on this key’s trading account, newest first. Each order names its `market_id`, `title` and `outcome`; the title and outcome are null for a market whose fixture started more than 7 days ago. Filter by status, venue, market, text in the market title or `client_order_id`,… - [Retrieve an order](https://docs.lean.xyz/api-reference/orders/retrieve-order.md): One API order by id, refreshed from its venues, with its market’s `title` and `outcome` and each leg’s status and the quantity filled so far. A canceled ioc order and its canceled legs carry `status_reason.code` `IOC_REMAINDER_CANCELED`: the venue canceled what did not fill at once, and `filled_quan… - [Amend an order](https://docs.lean.xyz/api-reference/orders/amend-order.md): Changes the limit price, the size or both of a resting good til canceled order on one venue. Lean cancels the order and, once the cancel is confirmed with its final fill, places a new good til canceled order on the same venue with the same post_only for the rest of the new size: the answer is the ne… - [Cancel an order](https://docs.lean.xyz/api-reference/orders/cancel-order.md): Cancels what is still resting of an open order on every venue it was placed on and returns the order once the venues answer. Shares already filled stay filled. - [Cancel every open order](https://docs.lean.xyz/api-reference/orders/cancel-all-orders.md): Cancels each open order of this key's trading account in this key's mode, optionally only on one venue or market, the same way canceling each order would. One failed cancel does not stop the rest; each result says what happened. Works while trading is paused. - [Set a cancel timer](https://docs.lean.xyz/api-reference/orders/set-cancel-after.md): A safety timer: unless this is called again in time, every open order of this key's trading account in this key's mode is canceled once the timeout runs out. Each call restarts the timer; 0 disarms it. The timer fires once and then disarms. - [Cancel several orders](https://docs.lean.xyz/api-reference/orders/cancel-orders-batch.md): Cancels each named order of this key's trading account in this key's mode, the same way canceling each order would. Name orders by id, by client_order_id or both, up to 50 in one call. One failed cancel does not stop the rest; each result says what happened, and an order that matches nothing fails w… - [List fills](https://docs.lean.xyz/api-reference/orders/list-fills.md): Executions on this key’s trading account, newest first, with price, quantity, fee and whether each fill made or took liquidity. Each fill names its `market_id`, `title` and `outcome`, or null when no market is listed for it. Filter by order, venue, market, time or text in the market title, and pass… - [Place a routed order](https://docs.lean.xyz/api-reference/orders/create-routed-order.md): Advanced. Book a cross-venue buy whose payment you sign yourself. - [Execute a routed order](https://docs.lean.xyz/api-reference/orders/execute-routed-order.md): Authorizes the payment of an order from POST /v1/routed-orders, with your signature over its `typed_data` or with Lean’s delegated signer, and starts the route. Call it before the payment expires. - [Create a stop loss or take profit](https://docs.lean.xyz/api-reference/stop-losses/create-stop-loss.md): Watches the best bid for shares this key’s trading account holds on the request’s venue and sells them once it reaches the trigger price. A stop_loss sells when the bid falls to trigger_price or below; a take_profit sells when it rises to trigger_price or above. The sale fills no lower than trigger_… - [List stop losses](https://docs.lean.xyz/api-reference/stop-losses/list-stop-losses.md): Stop losses and take profits of this key’s trading account in this key’s mode, newest first: every one still watching or selling, and those that ended in the last hour. - [Get a stop loss](https://docs.lean.xyz/api-reference/stop-losses/retrieve-stop-loss.md): One stop loss or take profit of this key’s trading account by id. - [Cancel a stop loss](https://docs.lean.xyz/api-reference/stop-losses/cancel-stop-loss.md): Stops a stop loss or take profit from watching the market, and stops a sale it has started. Canceling works while trading is paused. A live stop loss answers with cancel_requested_at set and its status unchanged; it reads canceled a moment later, once Lean has applied the cancel. A test stop loss re… - [Create a limit chase](https://docs.lean.xyz/api-reference/limit-chases/create-limit-chase.md): Rests a limit order on the request’s venue a set distance behind the best price on its own side, and moves it as that price moves until the order fills, is canceled or expires. A buy follows the best bid and a sell the best ask. The order never crosses the spread, and never rests beyond price_limit… - [List limit chases](https://docs.lean.xyz/api-reference/limit-chases/list-limit-chases.md): Limit chases of this key’s trading account in this key’s mode, newest first: every one still resting, and those that ended in the last hour. - [Get a limit chase](https://docs.lean.xyz/api-reference/limit-chases/retrieve-limit-chase.md): One limit chase of this key’s trading account by id. - [Cancel a limit chase](https://docs.lean.xyz/api-reference/limit-chases/cancel-limit-chase.md): Stops a limit chase and cancels its resting order. Shares it already bought or sold stay with the account. Canceling works while trading is paused. A live limit chase answers with cancel_requested_at set and its status unchanged; it reads canceled a moment later, once Lean has applied the cancel. A… - [List positions](https://docs.lean.xyz/api-reference/account/list-positions.md): Shares held by this key’s trading account on each venue, with average price, mark price and unrealized profit and loss. Each holding names its `market_id`, `title` and `outcome`, or null when no market is listed for it. Filter by venue, market or text in the market title. Kalshi and Polymarket US ac… - [Close positions](https://docs.lean.xyz/api-reference/account/close-positions.md): Sells each position of this key's trading account in this key's mode, optionally only on one venue or market, through the same checks and limits as POST /v1/orders. Each sell sells only what is held less what open sells already offer, on the venue that holds it, so a close never sells more than the… - [List balances](https://docs.lean.xyz/api-reference/account/list-balances.md): Cash held by this key’s trading account on each venue, in the collateral the venue trades in. Kalshi and Polymarket US cash belongs to the user, so every trading account of the user reads the same balance there. A venue that could not be read is listed in `unavailable`. - [Get profit and loss](https://docs.lean.xyz/api-reference/account/get-pnl.md): Realized, unrealized and total profit and loss of this key’s trading account, overall and per venue. Filter by `venue` or `market_id`. A live key reads its account’s profit and loss ledger, or for one market its positions there. A test key replays its simulated fills for realized profit and loss, an… - [Get profit and loss history](https://docs.lean.xyz/api-reference/account/get-pnl-history.md): Cumulative profit and loss of this key’s trading account at evenly spaced times from `start` to `end`, each point as of its time. The range is at most 365 days and 1000 points. A test key’s points have realized profit and loss only. - [Get risk](https://docs.lean.xyz/api-reference/account/get-risk.md): Exposure of this key’s trading account, per venue and in total: the cost basis and mark value of its positions, its cash, and the unfilled notional of its open orders. Also its largest positions and how its cost basis splits across markets and categories. Built from the same reads as positions, bala… - [Get account configuration](https://docs.lean.xyz/api-reference/account/retrieve-account-config.md): What this key may do, the spend limits an order placed with it is held to, where they come from, how much of the rolling 24 hour limit is left, the venues the account allows, its slippage cap, if it sets one, and whether trading is paused. - [Lower this key's limits](https://docs.lean.xyz/api-reference/account/lower-key-limits.md): A key may lower its own per order and rolling 24 hour limits. Raising them needs a signed in session in the dashboard; a raise is refused with `details.reason` `LIMIT_RAISE_NOT_ALLOWED`. - [Pause order placement](https://docs.lean.xyz/api-reference/account/pause-trading.md): Stops new orders for this key or for every key of its trading account, and stops queued orders that have not reached a venue yet. Reads, cancels and resting orders are unaffected. Only the Lean dashboard can resume. - [List deposit assets](https://docs.lean.xyz/api-reference/deposits/list-deposit-assets.md): Chains and tokens each venue accepts as deposits, with the provider’s minimum. Hyperliquid deposits arrive through Relay as spot USDC; sending to Hyperliquid’s own bridge lands in perps. The first instant bridge order that funds a Hyperliquid account never used before pays Hyperliquid’s one time 1 U… - [Get deposit addresses](https://docs.lean.xyz/api-reference/deposits/list-deposit-addresses.md): Addresses that fund the key’s trading account on one venue, as already created; this never creates one. An address created in the Lean app is returned here too. Each address not created yet is listed in `missing` with a `message` naming POST /deposits/addresses. Send only an asset GET /deposits/asse… - [Create deposit addresses](https://docs.lean.xyz/api-reference/deposits/create-deposit-addresses.md): Only needed if you haven’t already created a deposit address in the Lean app. Creates every deposit address the key’s trading account is missing on one venue and returns all of them. An address the provider cannot open right now is listed in missing while the others are still created and returned; c… - [Withdraw cash](https://docs.lean.xyz/api-reference/withdrawals/create-withdrawal.md): Withdraws cash from one venue of this key’s trading account to the address the request names. The request names the source venue and the asset it holds, the destination chain, asset and address, and the amount of the source asset. Each venue pays out one asset as usdc, on any chain that destination.… - [List withdrawals](https://docs.lean.xyz/api-reference/withdrawals/list-withdrawals.md): Withdrawals this key’s trading account made in this key’s mode, newest first. - [Get a withdrawal](https://docs.lean.xyz/api-reference/withdrawals/retrieve-withdrawal.md): One withdrawal of this key’s trading account by id. - [Quote a transfer](https://docs.lean.xyz/api-reference/transfers/quote-transfer.md): What moving cash from one venue of this key’s trading account to the other would cost and deliver, the smallest amount the route accepts and what the sending venue holds. It needs only the read scope and creates nothing. - [Create a transfer](https://docs.lean.xyz/api-reference/transfers/create-transfer.md): Creates a transfer of cash from one venue of this key’s trading account to the account’s own balance on the other venue. Transfers are simulated against test cash for test keys; live keys are refused with LIVE_TRANSFERS_UNAVAILABLE. Nothing moves until the transfer is executed with the owner’s signa… - [Execute a transfer](https://docs.lean.xyz/api-reference/transfers/execute-transfer.md): Authorizes and submits a transfer waiting for authorization, once. Send the owner’s signatures over `authorization.payloads` in order, or `delegated` to have Lean sign them with the account’s delegated signer. A transfer is submitted at most once and never retried; sending the same authorization aga… - [List transfers](https://docs.lean.xyz/api-reference/transfers/list-transfers.md): Transfers of this key’s trading account in this key’s mode, newest first. - [Get a transfer](https://docs.lean.xyz/api-reference/transfers/retrieve-transfer.md): One transfer of this key’s trading account by id, with its current status. - [Create a stream ticket](https://docs.lean.xyz/api-reference/streaming/create-stream-ticket.md): Mints a short lived ticket for one connection to the /v1/ws WebSocket, so the API key itself never travels over the socket. Connect, then send `{"op":"auth","ticket":""}` as the first frame. - [WebSocket](https://docs.lean.xyz/api-reference/streaming/websocket.md): Connect, authenticate and subscribe to the orders, positions, balances and book channels. - [Reset test mode](https://docs.lean.xyz/api-reference/test-mode/reset-test-mode.md): Deletes every simulated order, withdrawal, transfer, stop loss and limit chase of the test key’s trading account, made by any test key on that account and not only the calling key, which returns the account’s test balances to the starting amount and clears its test positions. Live keys are refused. - [Create an API key](https://docs.lean.xyz/api-reference/api-keys/create-api-key.md): Creates a test or live key on one of your trading accounts with the scopes and limits you choose, up to the account’s own. The secret is returned once in this response; store it, because it cannot be shown again. - [List API keys](https://docs.lean.xyz/api-reference/api-keys/list-api-keys.md): Every API key of the signed in user across their trading accounts, including revoked and expired keys. Secrets are never returned; each key shows only its prefix. - [Revoke an API key](https://docs.lean.xyz/api-reference/api-keys/revoke-api-key.md): Revokes a key at once, and requests with it are refused from then on. Revoking a key again returns it unchanged. - [Change an API key's limits](https://docs.lean.xyz/api-reference/api-keys/update-api-key-limits.md): Raises or lowers an active key's limits, up to its trading account's own. - [Pause an API key](https://docs.lean.xyz/api-reference/api-keys/pause-api-key.md): Stops one key placing new orders until you resume it. The key can still read and cancel, and its resting orders stay on the venues. Pausing a key that is already paused changes nothing. - [Resume an API key](https://docs.lean.xyz/api-reference/api-keys/resume-api-key.md): Lifts a pause you or the key set, so the key can place orders again. A pause Lean set can only be lifted by Lean. - [Get a trading account's API limits](https://docs.lean.xyz/api-reference/api-keys/retrieve-account-limits.md): The account's own API limits, allowed venues and slippage cap, and the limits every key on the account is held to. A limit the account has not set is reported as 100,000,000 USD, the most an account limit can be; each key still holds orders to its own limits. - [Set a trading account's API limits](https://docs.lean.xyz/api-reference/api-keys/update-account-limits.md): Replaces the account's own limits, allowed venues and slippage cap; a null slippage cap sets none. Each limit can be at most 100,000,000 USD; a null limit leaves that limit unset, so only each key's own limits apply. - [List trading pauses](https://docs.lean.xyz/api-reference/api-keys/list-trading-pauses.md): Every pause that stops orders from your API keys: pauses on a key, pauses on a trading account, and a platform wide halt if one is in force. Each shows who set it, why and since when. - [Pause API trading on a trading account](https://docs.lean.xyz/api-reference/api-keys/pause-account-api-trading.md): Stops every API key of one trading account placing new orders until you resume it. Keys can still read and cancel, and resting orders stay on the venues. - [Resume API trading on a trading account](https://docs.lean.xyz/api-reference/api-keys/resume-account-api-trading.md): Lifts a pause on a trading account so its keys can place orders again. A pause Lean set can only be lifted by Lean. ## OpenAPI Specs - [openapi](/api-reference/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.