Skip to main content
Each entry names the release version from info.version in the OpenAPI spec. Breaking changes are marked, with the date they take effect. See Versioning for what counts as breaking.
0.1.0: Kalshi and Polymarket US
Venues
  • Markets, quotes, books, trades, prices, orders, fills, positions, balances, PnL, risk, stop losses and limit chases cover Kalshi and Polymarket US as well as Polymarket and Hyperliquid. venue takes kalshi and polymarket_us wherever it names a trading venue.
  • Kalshi and Polymarket US accounts belong to the user, so every trading account and key of the user shares their cash and shares. A live order there goes out under the user’s API key for that venue, connected in the Lean app, and is refused with 403 FORBIDDEN without one. See Kalshi and Polymarket US.
  • A quote, preview or order that needs a Polymarket US book Lean has not loaded yet answers 503 UPSTREAM_ERROR with Retry-After. Send it again after that time.
  • A test key starts with 10,000 USD of simulated cash on Kalshi and on Polymarket US.
  • Stop losses and limit chases run on every venue. They no longer refuse hyperliquid.
  • post_only orders go to Kalshi, Polymarket US and Hyperliquid. gtd orders go to Kalshi, Polymarket and Polymarket US. A fok order goes whole to one venue: Polymarket, else Kalshi, else Polymarket US.
  • Paying from the other venue, best_price routes, self-signed routed orders, deposits, withdrawals and transfers stay on Polymarket and Hyperliquid only.
0.1.0: fee terms and fixture filters on markets, sizes on prices, batch previews, test-mode marks
Markets
  • Every market leg has fees: the formula (price_curve or notional_on_exit), taker_rate, maker_rate and, for price_curve, exponent. They are the terms the preview charges, so a client can set a fee-aware limit price before previewing. fees is null when the venue’s fee rate isn’t recorded. See Fees.
  • GET /v1/markets takes fixture (a fixture key) and group (a group key such as moneyline:game), so one event’s market group loads in one request instead of a whole league.
  • Every market leg has status, the venue market’s status (unopened, open, closed, resolving or resolved). An unopened or resolving leg has a live book on the Lean platform but stays tradable: false, because its venue refuses orders. See Legs.
Prices
  • GET /v1/prices returns best_bid_quantity and best_ask_quantity, top level and per venue: the shares at the best price, so a client can see how much an edge is worth before previewing.
  • Prices match the Lean platform’s orderbook. Best prices are snapped to the market’s tick. mid is the venue’s mid rounded down to the tick, and a book with only one side reads that side instead of null. One venue’s crossed book reads a spread of 0.
  • last_trade_price counts a Hyperliquid trade of the opposite outcome at 1 minus its price, as Polymarket’s already did, so it is the latest trade on either outcome.
Candles
  • GET /v1/markets/{id}/candles leaves out periods the Lean chart treats as unpriced (an open of 0 or a close below 0.001), as the chart does.
Orders and fills
  • Orders and fills carry the market’s title and outcome, as positions do.
  • A canceled ioc order and its canceled legs have status_reason.code IOC_REMAINDER_CANCELED; filled_quantity says how much filled first.
  • POST /v1/orders/preview-batch previews 1 to 25 orders in one request and returns each one’s preview or error in order. It needs only the read scope. See Preview orders (batch).
  • Orders carry remaining_quantity: the shares still working on the venues, 0 once the order is final. avg_fill_price is documented as excluding fees.
  • An order or leg the venue rejected or canceled after part of it filled reads canceled, and one whose whole size filled reads filled, as the Lean app reports them.
  • A Polymarket ioc or fok sell may go below the market’s minimum shares, down to 0.01, so a position under the minimum can be closed. A sell that can rest keeps the minimum.
  • Closing positions skips a Hyperliquid remainder under one whole contract instead of sending a sell the venue refuses.
Test mode
  • Test positions are marked as the Lean portfolio marks live ones: Polymarket at the last trade, Hyperliquid at the venue’s mid. GET /v1/pnl totals their unrealized profit and loss exactly as it does for a live key, so a position on a resolved market counts none. GET /v1/pnl/history stays realized-only for test keys. See Test mode.
Errors
  • A 400 VALIDATION_ERROR message names the first failing field and what is wrong with it, such as market_ids: At most 25 market ids per request; split larger sets across requests, and says how many more problems are in details.
Performance
  • Responses report key authentication time in the Server-Timing header (auth), and a key’s last-used time is written at most once a minute instead of on every request.
0.1.0: Rust SDK 0.1.0
Rust SDK
  • lean-api-sdk 0.1.0 is an async Rust client for the API. It is on crates.io once 0.1.0 is published; add it with Tokio.
  • Every endpoint is a method on lean_api::Client with typed requests and responses, generated from the 0.1.0 OpenAPI spec. A response that isn’t a success returns Error::Api with the HTTP status, the error code and the request ID.
  • GET requests are retried on connection errors, 429 and 5xx responses. Order placement and other writes are never retried.
  • Client::stream keeps a WebSocket open for orders, positions, balances and books, and reconnects after a drop.
  • The API itself is unchanged.
See Rust SDK.
0.1.0: TypeScript SDK 0.1.0 on npm
TypeScript SDK
  • @leanxyz/api-sdk 0.1.0 is on npm. Install it with npm install @leanxyz/api-sdk. It needs Node.js 22 or later.
  • Every endpoint is a method with typed requests and responses, generated from the 0.1.0 OpenAPI spec. A response that isn’t a success throws LeanApiError with the HTTP status, the error code and the requestId.
  • @leanxyz/api-sdk/stream keeps a WebSocket open for orders, positions, balances and books, and reconnects after a drop.
  • The API itself is unchanged.
See TypeScript SDK.
0.1.0: unknown query parameters refused
Requests
  • Every endpoint that takes query parameters returns 400 VALIDATION_ERROR for one it does not take, as GET /v1/markets already did, naming it in details. A misspelled filter such as GET /v1/orders?stauts=open used to be ignored and return every order. Breaking: takes effect on release; remove any parameter an endpoint does not list.
0.1.0: client_order_id lookups across keys, cursors tied to their list, clearer errors
Orders
  • GET /v1/orders?client_order_id= lists the orders any key of the account placed with that ID, not only the calling key’s, so an order placed before a key rotation can still be found. It combines with the other filters.
  • Quotes, previews and placement report a venue failure as 503 UPSTREAM_ERROR. They never returned 502; the reference listed it by mistake.
Paging
  • A cursor is tied to the list that issued it. An orders cursor sent to GET /v1/fills, or any cursor sent to another list, returns 400 VALIDATION_ERROR. Breaking: a cursor issued before this release is refused once with 400; page that list again from the start.
Errors
  • A path or method no endpoint serves returns the JSON 404 NOT_FOUND envelope, not plain text.
  • A malformed key returns 401 UNAUTHORIZED with “Invalid, expired or revoked API key”, the same as an unknown key, instead of “Missing API key”.
Funding
  • When a venue already has some deposit addresses, the deposit address note names only the network still missing one, such as Solana, and says the returned addresses are ready to use. Hyperliquid’s min_deposit_usd is null: it has no minimum. See Funding.
0.1.0: steady search results, and closed markets refused on quote and preview
Markets
  • GET /v1/markets with search looks only at the listings of games in the start window. The same search now returns the same markets every time; it used to drop nickname and typo matches, such as philly, when it ran slowly. One- and two-letter searches no longer return 503 UPSTREAM_ERROR.
  • A search that cannot finish in time returns 503 UPSTREAM_ERROR instead of a partial list.
  • GET /v1/markets/{id}/quote and POST /v1/orders/preview on a market Polymarket has stopped trading return 409 CONFLICT with details.reason: "MARKET_NOT_TRADABLE", as documented. They used to return 500, or 500 and 409 at random for a market with both a YES and a NO Polymarket listing. The OpenAPI spec now lists this 409 on both routes.
  • When Polymarket answers that check with a response Lean cannot read, quote and preview return 503 UPSTREAM_ERROR instead of 500.
  • POST /v1/orders/preview returns these errors, and 503 UPSTREAM_ERROR when a venue book can’t be read, as the quote does. It no longer answers 200 with a ROUTE_UNAVAILABLE warning for them; that warning now means routing is off or no route can take the order.
  • A leg whose venue market has closed now reads tradable: false. Closed markets used to show every leg as tradable.
0.1.0: profit and loss, risk and the Lean MCP server
Profit and loss
  • New GET /v1/pnl returns realized, unrealized and total profit and loss for the account and for each venue. Pass venue or market_id to narrow it.
  • New GET /v1/pnl/history returns profit and loss over time at a 1h or 1d interval, for up to 365 days and 1000 points. See Profit and loss.
Risk
  • New GET /v1/risk returns cost basis, mark value, cash and open order notional for the account and for each venue, with the largest positions and the split by market and by category. See Risk.
Account
  • GET /v1/account/config now returns scopes, what the key may do: read, trade, route and withdraw.
MCP server
  • The Lean MCP server lets an AI assistant use your key to read markets, orders, fills, positions, profit and loss, risk, stop losses, limit chases, deposits, withdrawals and transfers. Every tool that takes a market id also takes a venue symbol.
  • It is read only unless it starts with --enable-trading. Then a key with the trade scope can place, preview, amend and cancel orders, close positions, create stop losses and limit chases, pause trading and lower its own limits. Transfers also need the route scope. Withdrawals need only the withdraw scope. Only the Lean app resumes trading or raises a limit.
See Run the Lean MCP server.
0.1.0: withdrawals to more chains
Withdrawals
  • POST /v1/withdrawals pays USDC out on every chain the Lean app withdraws to: destination.chain is one of polygon, arbitrum, base, optimism, ethereum, bsc or solana, from either venue. A Solana withdrawal takes a Solana address, and every other chain a 0x address; an address the chain cannot take is refused with 400 VALIDATION_ERROR. GET /v1/withdrawals and GET /v1/withdrawals/{id} return the chain each withdrawal paid out on. See Withdrawals through the API.
0.1.0: market search matches the Lean app search
Markets
  • GET /v1/markets with search now finds markets the way the search box in the Lean app does. Every word is matched against Polymarket and Hyperliquid listing titles, with common team nicknames and small typos tried when few listings match. See Search by text.
  • Only markets with a matching listing are returned, not every market of the same game. Results keep their order by start time, and the other filters and cursor work as before.
  • search no longer matches a market by its league. A league name such as nba finds only the markets with a listing whose title contains it, such as some Hyperliquid listings. Use league to list a league.
  • A request with search can return 503 UPSTREAM_ERROR while search is briefly unavailable. Retry it.
0.1.0: filter positions, and find positions, orders and fills by text
Positions
  • GET /v1/positions takes venue, market_id and search. With venue, Lean reads only that venue, so only it can be listed in unavailable. See Read positions.
Orders and fills
  • GET /v1/orders and GET /v1/fills take search. It keeps the records on a market whose title or outcome contains the text, in any letter case, and pages with next_cursor as usual. See Find by text.
  • search must be 1 to 100 characters once spaces at either end are removed. Anything else returns 400 VALIDATION_ERROR.
0.1.0: venue symbols wherever a market id goes
Markets
  • Every path and field that takes a market id also takes a venue symbol that names one market: a Polymarket token id, a Hyperliquid book coin (#…, written %23… in a path), or a leg ticker that pays only one outcome. Responses, orders, fills and filters always use the market id. See Venue symbols.
  • An order named by a venue symbol trades only that listing, and a buy Lean routes for it can still be paid from the other venue. Quotes, books, trades, prices and the book stream channel named by a symbol read only that listing, so they price what the order would trade.
  • A book stream channel takes a venue symbol as well as a market id. Each book frame now carries a top level market_id: the id or symbol the channel was subscribed with. The book inside it still carries the market id. See Book.
  • A symbol that names more than one market, such as a Polymarket condition id, returns 400 VALIDATION_ERROR. An unknown symbol returns 404 NOT_FOUND, as an unknown market id does.
Breaking, effective 2026-11-12: in a REST path, query or body, a value that is neither a market id nor a venue symbol now returns 400 VALIDATION_ERROR instead of 404 NOT_FOUND. A mkt_… id Lean did not issue still returns 404 NOT_FOUND.
0.1.0: transfers between your venues
Transfers
  • POST /v1/transfers/quote shows what moving USDC from one of your account’s venues to the other costs: fee_usd, receive_usd, minimum_usd, available_usd and expires_at.
  • POST /v1/transfers creates a transfer to the account’s own balance on the other venue and returns the message to sign. Sending the same client_transfer_id again returns the same transfer. POST /v1/transfers/{id}/execute takes your signature, or "delegated" to have Lean sign.
  • GET /v1/transfers and GET /v1/transfers/{id} show each transfer from awaiting_authorization to completed, failed or expired.
  • Transfers count against the key’s limits and stop while the key or account is paused. A quote still answers while paused. They need the trade and route scopes. Transfers are test mode only for now: a live key gets 503 FEATURE_DISABLED with details.reason: "LIVE_TRANSFERS_UNAVAILABLE". See Transfers.
Test mode
  • POST /v1/test/reset also deletes the account’s test transfers and returns deleted_transfers.
0.1.0: limit chases
Limit chases
  • POST /v1/limit-chases rests a post only limit order on Polymarket a set distance behind the best price on its own side, given in offset_ticks or offset_price, and moves it as the book moves until it fills, is canceled or reaches expires_at. price_limit caps how far it follows. Hyperliquid does not run them, and a request for it is refused with 400 VALIDATION_ERROR. GET /v1/limit-chases, GET /v1/limit-chases/{id} and DELETE /v1/limit-chases/{id} read and cancel them. Each one counts against the key’s order and daily limits at the most it can trade for. A test key’s limit chases follow the public book and fill in simulation. What one has filled is listed in GET /v1/fills with order_id null, as a live limit chase’s fills are. POST /v1/test/reset also deletes them and returns deleted_limit_chases. See Limit chases.
0.1.0: market names on positions, older trades, fill filters and price candles
Fills
  • Each fill in GET /v1/fills now carries market_id, the market it filled on, or null when Lean cannot tie it to one.
  • GET /v1/fills takes market_id, filled_after and filled_before to narrow the list to one market or a time window. See Read fills.
Positions
  • Each position in GET /v1/positions and the positions stream channel now carries title and outcome beside market_id. All three are null whenever market_id is. See Reconcile.
Markets
  • Each market now carries title, the fixture, proposition and outcome in words.
  • GET /v1/markets/{id}/trades returns next_cursor. Pass it as cursor, with the same market and venue, to read older trades. See Recent trades.
  • New GET /v1/markets/{id}/candles returns open, high, low, close and volume per venue listing, from one second to two hours per candle. See Price candles.
0.1.0: order management
Orders
  • POST /v1/orders/cancel-batch cancels up to 50 orders in one call, named by id, client_order_id or both, with one result for each name. See Track and cancel.
  • post_only on POST /v1/orders and POST /v1/orders/preview places an order that only rests on the book. It runs on Hyperliquid, and an order that would trade at once is refused with details.reason POST_ONLY_WOULD_CROSS. See Post only orders.
  • PATCH /v1/orders/{id} changes the price, the size or both of a resting order. Lean cancels it and places a new order for the rest once the cancel is confirmed, answering 409 REPLACEMENT_PENDING until then, and the two name each other in the new replaces_order_id and replaced_by_order_id fields. The new order is placed as the key that sends the amend places one. See Amend an order.
  • type: "market" on POST /v1/orders and POST /v1/orders/preview trades at once with limit_price as an optional cap. Without one, a buy is capped at 0.99 and a sell at 0.01. It needs time_in_force ioc or fok. See Market orders.
  • time_in_force fok fills an order in full at once or cancels all of it, and gtd rests an order until the new expires_at. Both run on Polymarket, and a request for Hyperliquid is refused with 400 VALIDATION_ERROR. A fok buy is sized with notional. See Fill or kill and expiring orders.
  • Orders and previews show the new type and expires_at fields.
Withdrawals
  • POST /v1/withdrawals withdraws cash from a venue to the address the request names, within the key’s single and daily withdrawal limits. GET /v1/withdrawals and GET /v1/withdrawals/{id} read them back. It needs the new withdraw scope, which a live key takes when you turn on withdrawals for it in the Lean app. Both limits are optional. A request names its source venue and asset, its destination chain, asset and address, and the amount; the response adds the venue’s fee and the net_amount quoted to arrive. A live withdrawal pays USDC on Polygon from Polymarket’s pUSD and USDC on Arbitrum from Hyperliquid’s USDC; any other pair is refused with 400. It starts pending, and becomes completed or failed with a failure_reason as the venue settles it. The account must have trading enabled. POST /v1/test/reset also deletes test withdrawals and returns deleted_withdrawals. See Withdrawals through the API.
Stop losses and take profits
  • POST /v1/stop-losses sells shares the account holds on Polymarket once the best bid falls to a trigger price (stop_loss) or rises to it (take_profit). Hyperliquid does not run them, and a request for it is refused with 400 VALIDATION_ERROR. GET /v1/stop-losses, GET /v1/stop-losses/{id} and DELETE /v1/stop-losses/{id} read and cancel them, and a cancel shows in the new cancel_requested_at field. Each sale counts against the key’s order and daily limits at its trigger price. A test key’s stop losses are checked and listed but never sell. POST /v1/test/reset also deletes them and returns deleted_stop_losses. See Stop losses and take profits.
0.1.0: more fixes from agent testing
Orders
  • Breaking, effective 2026-11-12: when no venue that lists the market is open to the trading account, for example because the venue is not available in your region, POST /v1/orders/preview now returns the same 403 error as POST /v1/orders and the quote. It used to return 200 with a TRADING_UNAVAILABLE warning. See Preview.
  • Order docs now say where fees are: an order has no fee field, and its fees are the fee_usd of its fills. A live Hyperliquid buy fill shows fee_usd 0 because the buy pays its fee when the position closes or settles. See Limitations.
  • Breaking, effective 2026-11-12: an order you canceled reads cancel_requested until its venue confirms the cancel, then canceled, or filled if a fill beat the cancel. It used to keep reading open or partially_filled meanwhile. GET /v1/orders takes status=cancel_requested. See Statuses.
  • Orders carry filled_notional_usd, what the filled shares traded for across every leg. notional_usd stays the order at its own limit. See Orders.
  • A sell at 0.01, as a close without limit_price places, now shows the lowest limit among its legs as its limit_price, the protection the venue orders carry. It used to show 0.01.
  • An ioc buy can send notional, the dollars to spend, in place of quantity. Lean walks the books within your limit and slippage bound and never spends more than notional before fees. limit_price is optional with it. POST /v1/orders/preview and GET /v1/markets/{id}/quote take it too. See Buying a dollar amount.
  • An ioc buy sized with notional can now fill on Polymarket. One sized with quantity is still refused there, and the error now says to send notional.
  • Reading a filled Hyperliquid or Polymarket order with GET /v1/orders/{id} now brings its fills into GET /v1/fills. Before, the order could read filled a few seconds before its fills were listed. A Polymarket fill whose trade Polygon has not confirmed yet, or a fill of an order you have not read, can still be listed a few seconds later. See Limitations.
Closing positions
  • Each placed sell in a close is read back before the response, so a sell the venue matched at once reads filled with its filled quantity and average price. It used to read as first placed.
  • A close scoped to one market no longer includes positions that can’t be matched to a market the API trades. A close of every position still includes them.
Test mode
  • A test buy paid from the other venue now fills at the asks that venue’s public book shows. When those asks can’t fill the whole size within the limit, the buy is refused with 422 VALIDATION_ERROR, as a live one is. It used to fill at the limit. See Test mode.
  • Test positions now carry mark_price, the best bid on the venue’s public book, and unrealized_pnl_usd. Both used to be null.
Streaming
  • The Streaming page names the WebSocket URL, wss://api.lean.xyz/v1/ws.
0.1.0: fixes from agent testing
Markets
  • GET /v1/markets takes venue, polymarket or hyperliquid, to list only markets with a leg on that venue. See Query parameters.
  • A Polymarket leg the venue no longer trades now reads tradable: false, and a market with no tradable open leg reads closed.
  • Breaking, effective 2026-11-12: GET /v1/markets refuses a query parameter it does not know with 400 VALIDATION_ERROR. It used to ignore it and return the whole list.
  • Breaking, effective 2026-11-12: a request that needs the book of a market Polymarket has stopped trading returns 409 CONFLICT with details.reason: "MARKET_NOT_TRADABLE". It used to return 503 UPSTREAM_ERROR. See Errors.
Orders and account
  • Each item of GET /v1/positions carries market_id, the Lean market the position belongs to. market_id is null when no listed market currently matches the holding, for example a fixture that settled more than 7 days ago. It can also be null for a moment after an API restart or a failed market list load, until the market list loads. Closing still works because the close path resolves the market from the ticker.
  • POST /v1/orders/preview prices route_plan at the order’s limit. A limit at the best ask no longer warns, and a buy limit below the book reports limited_by: "depth", not "funds". The LIMIT_BELOW_ROUTE_PRICE preview warning is gone: ROUTE_LIMITED covers a limit the books cannot fill. See Preview.
  • GET /v1/balances answers within about 3 seconds. A venue that has not answered by then is listed in unavailable, and the other venues are still returned.
0.1.0: one-call orders across venues
Orders
  • POST /v1/orders now buys with cash held on the other venue in the same call. Lean moves the cash and buys on the venue with the book. The response carries route: { funding_venue, execution_venue }, or route: null when nothing was moved. See Paying from the other venue.
  • It needs the key’s route scope, trading enabled in the Lean app for a live key, and routing available. If any is missing, the order is refused as before with 422 VALIDATION_ERROR and details.reason: "INSUFFICIENT_FUNDS".
  • Read and trade keys made in the Lean app now include the route scope, in test and live mode. Keys made earlier keep their scopes: create a new key, or one with route through POST /api-keys, to use one-call routing. See Authentication.
  • Test keys get the same one call against the simulator. No real funds move.
  • POST /v1/routed-orders and POST /v1/routed-orders/{id}/execute remain for programs that sign each payment themselves. See Advanced: self-signed routed orders.
  • venues on POST /v1/orders keeps an order on the venues it names. A single venue places the order only there, or refuses it. The list can only narrow the account’s venues. See Choosing venues.
  • POST /v1/orders/preview honors venues, and shows the route a buy would take in route.
  • best_price on POST /v1/orders and POST /v1/orders/preview pays from the other venue whenever that costs less in all than buying where the account’s cash is. It is false by default. See Best price across venues.
Nothing breaking: an order that would have been refused with INSUFFICIENT_FUNDS can now fill.
Preview release
The first public preview of the Lean API, served at https://api.lean.xyz/v1.Markets
  • GET /v1/markets lists canonical sports markets, without naming a venue. Each leg carries the venue’s resolution terms, and each market says whether its venue listings were reviewed as the same proposition. See Markets.
  • GET /v1/markets/{id}/quote quotes a market across the venues that list it.
Orders
  • POST /v1/orders/preview prices an order and shows the route Lean would take.
  • POST /v1/orders places an order on Hyperliquid, Polymarket or both. client_order_id makes retries safe.
  • GET /v1/orders, GET /v1/orders/{id} and POST /v1/orders/{id}/cancel reconcile and cancel orders. Each order has legs, one per venue order, each with its own status and status_reason, and an avg_fill_price for the whole order.
  • Venue outcomes are order statuses: an unfilled ioc order is canceled, a venue refusal is rejected, and a submit the venue did not confirm is unconfirmed. See Order statuses.
Account
  • GET /v1/balances and GET /v1/positions read each venue, and report a venue that cannot be read as unavailable rather than as zero.
  • POST /v1/account/pause lets a key stop new orders for itself or its whole trading account. Only the Lean dashboard resumes. See Pause trading.
Keys
  • POST /api-keys, GET /api-keys and DELETE /api-keys/{id} manage keys, each with scopes and per order and daily limits.
  • Test keys simulate fills against simulated balances. See Test mode.