info.version in the
OpenAPI spec. Breaking changes are marked, with the date they take
effect. See Versioning for what counts as breaking.
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.
venuetakeskalshiandpolymarket_uswherever 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 FORBIDDENwithout 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_ERRORwithRetry-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_onlyorders go to Kalshi, Polymarket US and Hyperliquid.gtdorders go to Kalshi, Polymarket and Polymarket US. Afokorder goes whole to one venue: Polymarket, else Kalshi, else Polymarket US.- Paying from the other venue,
best_priceroutes, self-signed routed orders, deposits, withdrawals and transfers stay on Polymarket and Hyperliquid only.
Markets
- Every market leg has
fees: the formula (price_curveornotional_on_exit),taker_rate,maker_rateand, forprice_curve,exponent. They are the terms the preview charges, so a client can set a fee-aware limit price before previewing.feesisnullwhen the venue’s fee rate isn’t recorded. See Fees. GET /v1/marketstakesfixture(a fixture key) andgroup(a group key such asmoneyline: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,resolvingorresolved). Anunopenedorresolvingleg has a live book on the Lean platform but staystradable: false, because its venue refuses orders. See Legs.
GET /v1/pricesreturnsbest_bid_quantityandbest_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.
midis the venue’s mid rounded down to the tick, and a book with only one side reads that side instead ofnull. One venue’s crossed book reads aspreadof0. last_trade_pricecounts 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.
GET /v1/markets/{id}/candlesleaves 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 carry the market’s
titleandoutcome, as positions do. - A canceled
iocorder and its canceled legs havestatus_reason.codeIOC_REMAINDER_CANCELED;filled_quantitysays how much filled first. POST /v1/orders/preview-batchpreviews 1 to 25 orders in one request and returns each one’s preview or error in order. It needs only thereadscope. See Preview orders (batch).- Orders carry
remaining_quantity: the shares still working on the venues,0once the order is final.avg_fill_priceis 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 readsfilled, as the Lean app reports them. - A Polymarket
iocorfoksell may go below the market’s minimum shares, down to0.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 positions are marked as the Lean portfolio marks live ones: Polymarket at the last trade,
Hyperliquid at the venue’s mid.
GET /v1/pnltotals 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/historystays realized-only for test keys. See Test mode.
- A
400 VALIDATION_ERRORmessage names the first failing field and what is wrong with it, such asmarket_ids: At most 25 market ids per request; split larger sets across requests, and says how many more problems are indetails.
- Responses report key authentication time in the
Server-Timingheader (auth), and a key’s last-used time is written at most once a minute instead of on every request.
Rust SDK
lean-api-sdk0.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::Clientwith typed requests and responses, generated from the 0.1.0 OpenAPI spec. A response that isn’t a success returnsError::Apiwith 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::streamkeeps a WebSocket open for orders, positions, balances and books, and reconnects after a drop.- The API itself is unchanged.
TypeScript SDK
@leanxyz/api-sdk0.1.0 is on npm. Install it withnpm 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
LeanApiErrorwith the HTTPstatus, the errorcodeand therequestId. @leanxyz/api-sdk/streamkeeps a WebSocket open for orders, positions, balances and books, and reconnects after a drop.- The API itself is unchanged.
Requests
- Every endpoint that takes query parameters returns
400 VALIDATION_ERRORfor one it does not take, asGET /v1/marketsalready did, naming it indetails. A misspelled filter such asGET /v1/orders?stauts=openused to be ignored and return every order. Breaking: takes effect on release; remove any parameter an endpoint does not list.
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 returned502; the reference listed it by mistake.
- 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, returns400 VALIDATION_ERROR. Breaking: a cursor issued before this release is refused once with400; page that list again from the start.
- A path or method no endpoint serves returns the JSON
404 NOT_FOUNDenvelope, not plain text. - A malformed key returns
401 UNAUTHORIZEDwith “Invalid, expired or revoked API key”, the same as an unknown key, instead of “Missing API key”.
- 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_usdisnull: it has no minimum. See Funding.
Markets
GET /v1/marketswithsearchlooks 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 asphilly, when it ran slowly. One- and two-letter searches no longer return503 UPSTREAM_ERROR.- A search that cannot finish in time returns
503 UPSTREAM_ERRORinstead of a partial list. GET /v1/markets/{id}/quoteandPOST /v1/orders/previewon a market Polymarket has stopped trading return409 CONFLICTwithdetails.reason: "MARKET_NOT_TRADABLE", as documented. They used to return500, or500and409at random for a market with both a YES and a NO Polymarket listing. The OpenAPI spec now lists this409on both routes.- When Polymarket answers that check with a response Lean cannot read, quote and preview return
503 UPSTREAM_ERRORinstead of500. POST /v1/orders/previewreturns these errors, and503 UPSTREAM_ERRORwhen a venue book can’t be read, as the quote does. It no longer answers200with aROUTE_UNAVAILABLEwarning 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.
Profit and loss
- New
GET /v1/pnlreturns realized, unrealized and total profit and loss for the account and for each venue. Passvenueormarket_idto narrow it. - New
GET /v1/pnl/historyreturns profit and loss over time at a1hor1dinterval, for up to 365 days and 1000 points. See Profit and loss.
- New
GET /v1/riskreturns 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.
GET /v1/account/confignow returnsscopes, what the key may do:read,trade,routeandwithdraw.
- 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 thetradescope 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 theroutescope. Withdrawals need only thewithdrawscope. Only the Lean app resumes trading or raises a limit.
Withdrawals
POST /v1/withdrawalspays USDC out on every chain the Lean app withdraws to:destination.chainis one ofpolygon,arbitrum,base,optimism,ethereum,bscorsolana, from either venue. A Solana withdrawal takes a Solana address, and every other chain a0xaddress; an address the chain cannot take is refused with400 VALIDATION_ERROR.GET /v1/withdrawalsandGET /v1/withdrawals/{id}return the chain each withdrawal paid out on. See Withdrawals through the API.
Markets
GET /v1/marketswithsearchnow 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
cursorwork as before. searchno longer matches a market by its league. A league name such asnbafinds only the markets with a listing whose title contains it, such as some Hyperliquid listings. Useleagueto list a league.- A request with
searchcan return503 UPSTREAM_ERRORwhile search is briefly unavailable. Retry it.
Positions
GET /v1/positionstakesvenue,market_idandsearch. Withvenue, Lean reads only that venue, so only it can be listed inunavailable. See Read positions.
GET /v1/ordersandGET /v1/fillstakesearch. It keeps the records on a market whosetitleoroutcomecontains the text, in any letter case, and pages withnext_cursoras usual. See Find by text.searchmust be 1 to 100 characters once spaces at either end are removed. Anything else returns400 VALIDATION_ERROR.
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 legtickerthat 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
bookstream channel named by a symbol read only that listing, so they price what the order would trade. - A
bookstream channel takes a venue symbol as well as a market id. Eachbookframe now carries a top levelmarket_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 returns404 NOT_FOUND, as an unknown market id does.
400 VALIDATION_ERROR instead of 404 NOT_FOUND. A mkt_… id
Lean did not issue still returns 404 NOT_FOUND.Transfers
POST /v1/transfers/quoteshows what moving USDC from one of your account’s venues to the other costs:fee_usd,receive_usd,minimum_usd,available_usdandexpires_at.POST /v1/transferscreates a transfer to the account’s own balance on the other venue and returns the message to sign. Sending the sameclient_transfer_idagain returns the same transfer.POST /v1/transfers/{id}/executetakes your signature, or"delegated"to have Lean sign.GET /v1/transfersandGET /v1/transfers/{id}show each transfer fromawaiting_authorizationtocompleted,failedorexpired.- 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
tradeandroutescopes. Transfers are test mode only for now: a live key gets503 FEATURE_DISABLEDwithdetails.reason: "LIVE_TRANSFERS_UNAVAILABLE". See Transfers.
POST /v1/test/resetalso deletes the account’s test transfers and returnsdeleted_transfers.
Limit chases
POST /v1/limit-chasesrests a post only limit order on Polymarket a set distance behind the best price on its own side, given inoffset_ticksoroffset_price, and moves it as the book moves until it fills, is canceled or reachesexpires_at.price_limitcaps how far it follows. Hyperliquid does not run them, and a request for it is refused with400 VALIDATION_ERROR.GET /v1/limit-chases,GET /v1/limit-chases/{id}andDELETE /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 inGET /v1/fillswithorder_idnull, as a live limit chase’s fills are.POST /v1/test/resetalso deletes them and returnsdeleted_limit_chases. See Limit chases.
Fills
- Each fill in
GET /v1/fillsnow carriesmarket_id, the market it filled on, ornullwhen Lean cannot tie it to one. GET /v1/fillstakesmarket_id,filled_afterandfilled_beforeto narrow the list to one market or a time window. See Read fills.
- Each position in
GET /v1/positionsand thepositionsstream channel now carriestitleandoutcomebesidemarket_id. All three arenullwhenevermarket_idis. See Reconcile.
- Each market now carries
title, the fixture, proposition and outcome in words. GET /v1/markets/{id}/tradesreturnsnext_cursor. Pass it ascursor, with the same market andvenue, to read older trades. See Recent trades.- New
GET /v1/markets/{id}/candlesreturns open, high, low, close and volume per venue listing, from one second to two hours per candle. See Price candles.
Orders
POST /v1/orders/cancel-batchcancels up to 50 orders in one call, named by id,client_order_idor both, with one result for each name. See Track and cancel.post_onlyonPOST /v1/ordersandPOST /v1/orders/previewplaces an order that only rests on the book. It runs on Hyperliquid, and an order that would trade at once is refused withdetails.reasonPOST_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, answering409REPLACEMENT_PENDINGuntil then, and the two name each other in the newreplaces_order_idandreplaced_by_order_idfields. The new order is placed as the key that sends the amend places one. See Amend an order.type: "market"onPOST /v1/ordersandPOST /v1/orders/previewtrades at once withlimit_priceas an optional cap. Without one, a buy is capped at0.99and a sell at0.01. It needstime_in_forceiocorfok. See Market orders.time_in_forcefokfills an order in full at once or cancels all of it, andgtdrests an order until the newexpires_at. Both run on Polymarket, and a request for Hyperliquid is refused with400 VALIDATION_ERROR. Afokbuy is sized withnotional. See Fill or kill and expiring orders.- Orders and previews show the new
typeandexpires_atfields.
POST /v1/withdrawalswithdraws cash from a venue to the address the request names, within the key’s single and daily withdrawal limits.GET /v1/withdrawalsandGET /v1/withdrawals/{id}read them back. It needs the newwithdrawscope, which a live key takes when you turn on withdrawals for it in the Lean app. Both limits are optional. A request names itssourcevenue and asset, itsdestinationchain, asset and address, and theamount; the response adds the venue’sfeeand thenet_amountquoted 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 with400. It startspending, and becomescompletedorfailedwith afailure_reasonas the venue settles it. The account must have trading enabled.POST /v1/test/resetalso deletes test withdrawals and returnsdeleted_withdrawals. See Withdrawals through the API.
POST /v1/stop-lossessells 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 with400 VALIDATION_ERROR.GET /v1/stop-losses,GET /v1/stop-losses/{id}andDELETE /v1/stop-losses/{id}read and cancel them, and a cancel shows in the newcancel_requested_atfield. 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/resetalso deletes them and returnsdeleted_stop_losses. See Stop losses and take profits.
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/previewnow returns the same403error asPOST /v1/ordersand the quote. It used to return200with aTRADING_UNAVAILABLEwarning. See Preview. - Order docs now say where fees are: an order has no fee field, and its fees are the
fee_usdof its fills. A live Hyperliquid buy fill showsfee_usd0because the buy pays its fee when the position closes or settles. See Limitations. - Breaking, effective 2026-11-12: an order you canceled reads
cancel_requesteduntil its venue confirms the cancel, thencanceled, orfilledif a fill beat the cancel. It used to keep readingopenorpartially_filledmeanwhile.GET /v1/orderstakesstatus=cancel_requested. See Statuses. - Orders carry
filled_notional_usd, what the filled shares traded for across every leg.notional_usdstays the order at its own limit. See Orders. - A sell at
0.01, as a close withoutlimit_priceplaces, now shows the lowest limit among its legs as itslimit_price, the protection the venue orders carry. It used to show0.01. - An
iocbuy can sendnotional, the dollars to spend, in place ofquantity. Lean walks the books within your limit and slippage bound and never spends more thannotionalbefore fees.limit_priceis optional with it.POST /v1/orders/previewandGET /v1/markets/{id}/quotetake it too. See Buying a dollar amount. - An
iocbuy sized withnotionalcan now fill on Polymarket. One sized withquantityis still refused there, and the error now says to sendnotional. - Reading a filled Hyperliquid or Polymarket order with
GET /v1/orders/{id}now brings its fills intoGET /v1/fills. Before, the order could readfilleda 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.
- Each placed sell in a close is read back before the response, so a sell the venue matched at once
reads
filledwith 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.
- 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, andunrealized_pnl_usd. Both used to benull.
- The Streaming page names the WebSocket URL,
wss://api.lean.xyz/v1/ws.
Markets
GET /v1/marketstakesvenue,polymarketorhyperliquid, 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 readsclosed. - Breaking, effective 2026-11-12:
GET /v1/marketsrefuses a query parameter it does not know with400 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 CONFLICTwithdetails.reason: "MARKET_NOT_TRADABLE". It used to return503 UPSTREAM_ERROR. See Errors.
- Each item of
GET /v1/positionscarriesmarket_id, the Lean market the position belongs to.market_idisnullwhen no listed market currently matches the holding, for example a fixture that settled more than 7 days ago. It can also benullfor 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/previewpricesroute_planat the order’s limit. A limit at the best ask no longer warns, and a buy limit below the book reportslimited_by: "depth", not"funds". TheLIMIT_BELOW_ROUTE_PRICEpreview warning is gone:ROUTE_LIMITEDcovers a limit the books cannot fill. See Preview.GET /v1/balancesanswers within about 3 seconds. A venue that has not answered by then is listed inunavailable, and the other venues are still returned.
Orders
-
POST /v1/ordersnow 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 carriesroute: { funding_venue, execution_venue }, orroute: nullwhen nothing was moved. See Paying from the other venue. -
It needs the key’s
routescope, trading enabled in the Lean app for a live key, and routing available. If any is missing, the order is refused as before with422 VALIDATION_ERRORanddetails.reason: "INSUFFICIENT_FUNDS". -
Read and trade keys made in the Lean app now include the
routescope, in test and live mode. Keys made earlier keep their scopes: create a new key, or one withroutethroughPOST /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-ordersandPOST /v1/routed-orders/{id}/executeremain for programs that sign each payment themselves. See Advanced: self-signed routed orders. -
venuesonPOST /v1/orderskeeps 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/previewhonorsvenues, and shows the route a buy would take inroute. -
best_priceonPOST /v1/ordersandPOST /v1/orders/previewpays from the other venue whenever that costs less in all than buying where the account’s cash is. It isfalseby default. See Best price across venues.
INSUFFICIENT_FUNDS can now fill.The first public preview of the Lean API, served at
https://api.lean.xyz/v1.MarketsGET /v1/marketslists 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}/quotequotes a market across the venues that list it.
POST /v1/orders/previewprices an order and shows the route Lean would take.POST /v1/ordersplaces an order on Hyperliquid, Polymarket or both.client_order_idmakes retries safe.GET /v1/orders,GET /v1/orders/{id}andPOST /v1/orders/{id}/cancelreconcile and cancel orders. Each order haslegs, one per venue order, each with its ownstatusandstatus_reason, and anavg_fill_pricefor the whole order.- Venue outcomes are order statuses: an unfilled
iocorder iscanceled, a venue refusal isrejected, and a submit the venue did not confirm isunconfirmed. See Order statuses.
GET /v1/balancesandGET /v1/positionsread each venue, and report a venue that cannot be read as unavailable rather than as zero.POST /v1/account/pauselets a key stop new orders for itself or its whole trading account. Only the Lean dashboard resumes. See Pause trading.
POST /api-keys,GET /api-keysandDELETE /api-keys/{id}manage keys, each with scopes and per order and daily limits.- Test keys simulate fills against simulated balances. See Test mode.