Send the body as JSON with
Content-Type: application/json, here and for POST /v1/orders/preview. A body
sent without that header is refused with 400 VALIDATION_ERROR.
The response is the order, plus route. Here the account had no cash on Polymarket, so Lean paid
with its cash on Hyperliquid and bought on Polymarket:
id:
route is on the placement response only, including a replay of the same client_order_id. It is
null when Lean paid for the order on the venue it bought on. See
Paying from the other venue.
Lean routes each order across the venues it may use:
- A buy is split across eligible venues by best price.
- A sell takes the best bids across the venues that hold the shares, up to what each venue holds.
- Live orders route to Kalshi, Polymarket, Polymarket US and Hyperliquid. Test orders are simulated and never reach a venue.
title and outcome name the order’s market as GET /v1/markets does. They are null for a
market whose fixture started more than 7 days ago, and for a moment after an API restart.
legs has one entry per venue order, with its venue, ticker, side, quantity,
filled_quantity, avg_fill_price, status and status_reason. When the order went to one venue,
the order’s own venue, ticker and side name it. When it was split, they are null; read legs
instead. status, filled_quantity and avg_fill_price on the order always cover every leg:
avg_fill_price is the price weighted by size across the legs that filled, before fees, and null
until every filled leg has a price. remaining_quantity is the shares still working on the venues,
the unfilled size of each live leg, and 0 once the order is final.
notional_usd is the order at its own limit, the amount checked against your key’s limits. A
sell counts at the limits of its legs, the least it sells for, and toward the rolling day, but
only takes risk off, so no notional limit refuses it: a close works however much the day has traded.
filled_notional_usd is what the filled shares traded for across every leg, 0 before any fill,
and null until every filled leg has a price. A sell at 0.01, as a close without a limit_price
places, sells into the bids, down to the slippage bound below the best bid when one is set. Its limit_price shows the lowest
limit among its legs, the price the venue orders are protected by, rather than 0.01.
Preview shows the split before you place the order, in execution.legs.
Kalshi and Polymarket US
Kalshi and Polymarket US accounts belong to the user, not to one trading account. Every trading account and key of the user shares the same cash and shares there, soGET /v1/balances and
GET /v1/positions show the same Kalshi and Polymarket US figures under each of them.
- A live order on either venue goes out under the user’s own API key for that venue, connected in
the Lean app. Without one, an order that needs that venue is refused with
403 FORBIDDEN. - Polymarket US reads its book from a live copy that starts on the first read of a market. Until
it is ready, a quote, preview or order that needs that book is refused with
503 UPSTREAM_ERROR. It is safe to retry after a moment. - Cash can’t move to or from these venues through Lean. A buy there is paid with the cash already on that venue.
Post only orders
Setpost_only: true to make sure an order adds liquidity and never trades against a resting
order when it arrives. A post only order:
- needs
time_in_forcegtcand cannot usebest_price. Any other combination is refused with400 VALIDATION_ERROR. - is placed on Kalshi, Polymarket US and Hyperliquid, since Polymarket cannot rest a post only
order. On a market with none of those listings, or with
venuesthat leave all three out, it is refused with400 VALIDATION_ERROR. - is refused with
422 VALIDATION_ERRORanddetails.reason: "POST_ONLY_WOULD_CROSS"when the books, as Lean last read them, would fill any of it at once. Theclient_order_idis not used up, so you can send it again at a price further from the other side of the book.
rejected with no fills.
Preview shows the same refusal as a POST_ONLY_WOULD_CROSS warning.
Market orders
Settype: "market" to trade at once at the best prices the books offer. A market order:
- needs
time_in_forceiocorfok. Withgtcorgtdit is refused with400 VALIDATION_ERROR. - places each venue order 1 cent past the worst price its quantity reaches in that venue’s book, above it for a buy and below it for a sell, as the Lean trading terminal does.
- takes
limit_priceandmax_slippage_bpsas optional extra caps. Withoutlimit_pricea buy is capped at0.99and a sell at0.01. - fills a buy on Polymarket only when the buy is sized with
notional, like any immediate buy there. A sell is sized withquantity.
type, so you can read back what was placed.
Fill or kill and expiring orders
time_in_force fok fills the whole order at once or cancels all of it. Nothing fills in part. A
fok order that cannot fill in full ends canceled with filled_quantity 0.
time_in_force gtd rests like gtc until expires_at, then the venue expires it and it reads
expired. expires_at must be at least three minutes and at most thirty days away.
Hyperliquid has no fill or kill and no order expiry, so:
- a
fokorder is placed whole on one venue: Polymarket, else Kalshi, else Polymarket US. Fill or kill holds only within one venue’s book. - a
gtdorder is placed on Kalshi, Polymarket and Polymarket US. - on a market with none of those listings, or with
venuesthat leave them all out, the order is refused with400 VALIDATION_ERROR. - Polymarket takes a
fokbuy bynotionalonly, so afokbuy sized withquantitygoes to Kalshi or Polymarket US. With neither listed, it is refused with400 VALIDATION_ERROR. expires_atwithoutgtd,gtdwithoutexpires_at, or an expiry outside the window is refused with400 VALIDATION_ERROR.
expires_at, and null for any order without one.
Choosing venues
By default an order may use every venue the trading account allows. To keep it on some of them, list them invenues:
- With one venue, the order is placed only there. If that venue can’t fill or pay for it, the order is refused; Lean does not send it elsewhere.
venuescan only narrow the account’s venues. Naming a venue the account doesn’t allow refuses the order with422 VALIDATION_ERRORanddetails.reason: "VENUE_NOT_ALLOWED", even beside one it allows.details.allowed_venueslists the venues the account allows.- Paying from the other venue also stays inside
venues. With["polymarket"], Lean never uses cash on Hyperliquid for the order. - List each venue once. An empty list is refused with
400 VALIDATION_ERROR. - A retry with the same
client_order_idmust name the same venues, in any order. Other venues make it a different body, which returns409 CONFLICT.
Paying from the other venue
Each venue keeps its own cash. When a buy can’t be paid for on the venues with a book for it, but the account holds cash on the other venue, Lean moves that cash and buys on the venue with the book, in the same call. This works between Polymarket and Hyperliquid only; a buy on Kalshi or Polymarket US is paid with the cash already there. The response names both venues inroute:
Lean pays from the other venue only when all of these hold:
- The key has the
routescope as well astrade. A Read and trade key made in the Lean app has both, in test and live mode. A key made before one-call routing shipped (see the changelog) doesn’t: create a new one, or create one withroutethrough Create an API key. See Authentication. - With a live key, the account has trading enabled in the Lean app. A test key doesn’t need this.
- Routing is available for the order.
venues, if set, names both Polymarket and Hyperliquid.
422 VALIDATION_ERROR with
details.reason: "INSUFFICIENT_FUNDS".
- A live routed order can read
pendingwhile Lean moves the cash. Read it back withGET /v1/orders/{id}until it is final. - With a test key, the same call routes between the simulated balances. No real funds move. See Test mode.
- Only buys move cash. A sell is placed on the venues that hold the shares. Shares can’t move between venues.
Best price across venues
By default Lean pays from the other venue only when the account can’t pay for a buy where its cash is. Setbest_price: true to also do it when it is cheaper. Lean compares what the buy would cost
where the account’s cash is with what it would cost through a route that moves cash from the other
venue, fees included, and takes the cheaper one:
- When the route costs less in all, the buy goes through it and
routenames both venues. - Otherwise the buy is placed directly and
routeisnull. That includes a route Lean can’t price at the moment. - The route needs everything paying from the other venue needs,
including the key’s
routescope. When any of it is missing, the buy is placed directly. - It changes nothing when
venuesnames a single venue. - A test key prices a route at the order’s
limit_price, so in test mode the route wins only when the direct buy’s fees cost more. - Sells are unchanged. A sell already takes the best bids across every venue that holds the shares.
best_priceis part of the body a retry must repeat. The sameclient_order_idwith a differentbest_pricereturns409 CONFLICT.
route is set when the buy would go
through a route.
Slippage
max_slippage_bps is an optional extra cap on how far each venue order may trade from the best
price on its own venue’s book: above that venue’s best ask for a buy, below its best bid for a sell.
100 is 1%. Without one, a limit order trades to its limit_price and a market order to 1 cent
past the worst price its quantity reaches, as the Lean trading terminal places them.
- Each venue order is placed at
limit_price, tightened to the bound and moved onto the venue’s price tick: down for a buy, up for a sell. With the best ask at0.50andmax_slippage_bps: 100, a buy pays at most0.505on that venue, which is0.50on a0.01tick. - The bound never loosens
limit_price. - Each venue is measured against its own book, not the best price across venues, so venues quoting different prices can each fill.
- Leave it out to use the account’s
max_slippage_bpsinGET /v1/account/config, or no cap when that isnull.0is a bound too: each venue order trades only at its venue’s best price. - Preview shows the bound the order would use in
execution.max_slippage_bps,nullfor none. - A retry must send the same
max_slippage_bps, or leave it out again. A different value, or a value where the first body had none, returns409 CONFLICT.
All or none
Withall_or_none: true and time_in_force ioc or fok, Lean places the order only if the
books, as it reads them, fill the whole quantity within limit_price and the slippage bound. If they
don’t, the order is refused with 422 VALIDATION_ERROR and details.reason: "INSUFFICIENT_DEPTH",
and nothing is placed.
- It is best effort. Each venue order is placed on its own, and a book can change between the read and the fill, so a partial fill is still possible.
all_or_noneneedstime_in_forceiocorfok. Withgtcorgtdthe order is refused with400 VALIDATION_ERROR.- Preview warns with
INSUFFICIENT_DEPTHwhen the books can’t fill it in full. all_or_noneis part of the body a retry must repeat.
Price ticks
Each venue takes prices only on its own grid, its tick:limit_price must be above 0 and below 1, and on the tick of every venue that could place the
order. Lean never rounds it. A limit_price off a venue’s tick, such as 0.425 for a market
Polymarket trades on a 0.01 tick, is refused with 400 VALIDATION_ERROR: “limit_price is finer
than the price tick of a venue that could place it”. To trade at a finer price on one venue, name
only that venue in venues. Preview refuses the same body the same way.
Idempotency
client_order_id makes placement safe to retry:
- The same ID with the same body returns the original order. Nothing new is placed.
- The same ID with a different body returns
409 CONFLICT. - An ID is used once, even if that order was rejected.
- Close positions takes a
client_order_idof up to 40 characters. Each sell it places gets<close id>-close-<hash>-<hash>, which only the close response returns.
1
Choose and save the ID first
Write
client_order_id to your own storage before you send the request.2
On a timeout or network error, look it up
orders list means Lean never recorded the order. Anything
else is the order; if two of your keys reused the ID, each one’s order is listed.3
Retry only with the same ID
Resending the same body with the same ID returns the stored order. Never resend the order
with a new ID until you know the first one was not placed.
What placement returns
Once Lean has recorded the order,POST /v1/orders always answers 200 with the order after
every venue answered. What the venues did is in status and in each leg, not in an error:
An error status means Lean placed nothing, with one exception:
422 VALIDATION_ERROR: a key limit or a check before any venue refused the order.503 UPSTREAM_ERROR: a venue failed before anything was placed. When the response carriesRetry-After, a venue timed out or dropped the connection, so the order may or may not have reached it. Look it up byclient_order_idbefore you send it again.
When the venue does not confirm
Anunconfirmed order or leg reads: “The venue did not confirm this order. Read it back by
client_order_id; do not resend it.” It may or may not be on the venue. Read it with
GET /v1/orders?client_order_id=... or GET /v1/orders/{id}:
- If the venue has it working, it reads
open(or filled) andstatus_reasonclears. - If the venue still has no record of it ten minutes after placement, it reads
rejectedwithstatus_reason.codeVENUE_UNKNOWN. Only then is it safe to place it again, with a newclient_order_id.
Track and cancel
GET /v1/orders/{id}refreshes the order from its venue. A test order is never sent to a venue; reading it fills what rests against the public books. See Test mode.- If a venue cannot be read or reached,
GET /v1/orders/{id}returns503 UPSTREAM_ERRORand the stored order is unchanged. A cancel returns the same error when a venue cannot be reached: that venue’s leg is not canceled, though legs on other venues may be. Read the order again before you assume a cancel happened. GET /v1/orderslists stored orders, newest first, withnext_cursorfor paging. Narrow it withstatus,venue,market_idorclient_order_id, or withsearchfor text in the title or outcome of the order’s market. See Find by text.created_afterandcreated_beforenarrow the list to orders Lean recorded at or after, and before, a time. Send UTC ISO 8601 times ending inZ, such as2026-11-10T12:00:00Z. A time with an offset such as+00:00, or a date alone, returns400 VALIDATION_ERROR.client_order_idmatches the orders any key of the account placed with that ID, and combines with the other filters like any of them.- Canceling a finished order, or one the venue never confirmed, returns
409 CONFLICT. - A cancel stops every leg that is still working. Most stop at once. A leg that can’t be stopped
at once reads
cancel_requested, with acancel_requested_attime, until its venue confirms it, and the order readscancel_requestedtoo. Read the order back until it iscanceled, orfilledif a fill beat the cancel.
order_ids, client_order_ids or both, up to
50 in all:
- Each order is canceled the same way a single cancel would cancel it, and one failure never stops
the rest. The call answers
200with one row inresultsfor each name you sent, in the order you sent them:order_idsfirst, thenclient_order_ids. - A row’s
statusiscanceled,finishedfor an order that had already finished (itsordershows how), orfailedwith anerror. A name that matches no order of this key fails withNOT_FOUND. A row that failed for another reason carries the order as it stands, so you can see which legs are still open. - An order named twice, by its id and by its
client_order_id, is canceled once, and both rows show that one result. - Batch cancels draw on the same rate limit as other cancels and work while trading is paused.
Amend an order
Change the price, the size or both of a resting order withPATCH /v1/orders/{id}:
Send at least one of
limit_price and quantity. Only an open or partially_filled order with
time_in_force gtc that rests on one venue can be amended. A routed order, an order split across
venues, or an ioc, fok or gtd order is refused with 409 CONFLICT and
details.reason: "ORDER_NOT_AMENDABLE".
A finished order is refused with ORDER_NOT_OPEN. The new size must be more than what already
filled. Amends are refused while trading is paused.
No venue order is changed in place. Lean cancels the order and places a new gtc order on the
same venue, with the same post_only, for the rest of the new size at the new price. The answer is
200 with the new order, whose replaces_order_id names the old one. The old order reads
canceled, with replaced_by_order_id naming the new one. Each order keeps the fills of its own
venue order.
The new order is placed as the key that sends the amend places one. Before the old order is
canceled, Lean checks the new order as though the old one were already gone: the new price and size
against the venue, a post_only price that would trade at once (POST_ONLY_WOULD_CROSS), the
key’s limits, the account’s allowed venues, the rolling day and the account’s cash or shares, with
what the old order holds counted as free. Any refusal leaves the order as it was.
The replacement waits for the cancel:
- The old order can fill until its cancel lands, so Lean places the new order only once the cancel
is confirmed with the old order’s final fill, and sizes it from what had filled by then.
Hyperliquid confirms the cancel within the request. A live cancel on another venue, such as
Polymarket, can be confirmed a moment after it is requested, so the first amend can answer
409 CONFLICTwithdetails.reason: "REPLACEMENT_PENDING"and nothing placed. Send the same amend again once the old order readscanceled; that amend places the new order. - If the old order filled to the new size or more, nothing is placed and the amend is refused
with
ORDER_NOT_OPEN. - If something changes between that check and the new order, for example another order spends the cash, the new order can still be refused once the old one is canceled. The old order then stays canceled and nothing rests in its place.
- An order that was already replaced is refused with
ORDER_REPLACED, anddetails.replaced_by_order_idnames the order to amend instead.
Pause trading
If your program misbehaves, a key withtrade can stop new orders at once:
scopeisapi_keyto pause this key, ortrading_accountto pause every key of its trading account.reasonis optional, up to 200 characters.- The pause also stops queued orders that have not reached a venue yet. Reads, cancels and resting orders are unaffected, so cancel resting orders yourself if you want them gone.
- The response lists what now pauses this key in
paused.key,paused.accountandpaused.global, eachnullor{ reason, source, since }. - A key cannot resume trading. Resume from the Lean dashboard. A pause with
sourceoperatorwas set by Lean, and only Lean can lift it.
503 FEATURE_DISABLED with details.reason
TRADING_PAUSED and details.scope api_key or trading_account. A preview answers with
would_submit: false and a TRADING_UNAVAILABLE warning.
Reconcile
An accepted response is not proof of a fill. To reconcile an order:- Read the order with
GET /v1/orders/{id}. Checkstatus,filled_quantityandavg_fill_price, then each entry inlegs: itsstatus,filled_quantity,avg_fill_priceandvenue_order_id. - Read
GET /v1/positionsand check the position for each leg’svenue,tickerandside. Match on those three fields. Each position also names itsmarket_id,titleandoutcome, so you can match it to the market you ordered. All three arenullwhen no listed market currently matches the holding, for example a fixture that started more than 7 days ago. They 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. - Read
GET /v1/balancesand compare the change on each venue with that leg’sfilled_quantity × avg_fill_priceplus thefee_usdof its fills inGET /v1/fills. For an order with aroute, the funding venue’s change also includesroute.costs.network_cost_usd.
unavailable. It is never reported as an empty
position or a zero balance. Do not reconcile against a venue listed in unavailable.
Read positions
GET /v1/positions lists what you hold on each venue. Narrow the list with any of these query
parameters:
A
venue the API does not support returns 400 VALIDATION_ERROR.
Read fills
GET /v1/fills lists your fills, newest first. Each fill names its order_id and its
market_id, with the market’s title and outcome. Either ID is null when Lean cannot tie the
fill to one, for example a fill from an order placed outside the API on a market the API does not
list; title and outcome are then null too. A test order’s fill names its order’s market, and
its title and outcome are null once the market’s fixture started more than 7 days ago.
Narrow the list with any of these query parameters:
Send times in UTC ending in
Z, such as 2026-11-10T12:00:00Z. A time with an offset such as
+00:00, a date alone, or anything else returns 400 VALIDATION_ERROR. To read every fill in a
window, page with next_cursor and keep the same parameters.
Find by text
GET /v1/positions, 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. A record on a market the
API does not list never matches.
- Spaces at either end are ignored. The text must then be 1 to 100 characters, or the request
returns
400 VALIDATION_ERROR. searchcombines with the other parameters. Each record must match all of them.- Orders and fills page as usual. Pass
next_cursorback ascursorwith the samesearchto read the next page.
Profit and loss
GET /v1/pnl returns your realized, unrealized and total profit and loss in USD, for the whole
account and for each venue. Realized counts what closed and reduced positions made after fees.
Unrealized values your open positions at their current price. Pass venue or market_id to read
one venue or one market.
A venue that cannot be read right now is listed in unavailable, and its unrealized and total are
null. Its realized amount still counts. A market Lean does not know returns 404 NOT_FOUND.
GET /v1/pnl/history returns the same amounts as points over time, each one cumulative as of its
ts. Choose the spacing with interval, 1h or 1d (the default), and the range with start
and end as ISO 8601 timestamps. Without them you get the last 30 days. A range longer than 365
days, or with more than 1000 points at the chosen interval, returns 400 VALIDATION_ERROR.
A test key replays its simulated fills for realized, and values its simulated positions at the
midpoint of their venue’s public book for unrealized. Unrealized and total are null while one of
those positions has no mark. Its history has realized only, because past marks of test positions
aren’t kept. See Test mode.
Risk
GET /v1/risk sums up your exposure from the same data as positions, balances and orders, for the
whole account and for each venue:
Each
share is a fraction of the cost basis you know the cost of, from 0 to 1, to four decimal
places. A routed order whose venue order is not placed yet counts in the total open_orders but in
no venue’s.
A venue that cannot be read right now is listed in unavailable. Its values are null, and so is
every total they feed, rather than a sum that leaves it out. A test key’s positions are marked as
live ones are (see Test mode), and a position with no mark makes the mark values it
counts toward null.
Kickoff
Hyperliquid outcome markets do not cancel resting orders when a game starts. Agtc order left on the book
can fill in play at a price that no longer reflects the game.
Buying a dollar amount
Anioc or fok buy can name the dollars to spend instead of the shares to buy. Send notional in
place of quantity:
- Lean walks the venue books from the best ask until the dollars are spent, within your
limit_priceand slippage bound, if set. The order’slimit_priceis the worst price that walk reaches, and itsquantityis the shares the dollars buy at that price, rounded down to what the venues take. Hyperliquid takes whole shares only. - The order never spends more than
notionalbefore fees. A better price than the limit spends less, and on Polymarket it can buy a few more shares thanquantityfor the same dollars. notional_usd, and the amount checked against your key’s limits, is the order’squantityat itslimit_price. It is never more thannotional.limit_priceis optional withnotional. Without it the walk stops at0.99, or at the slippage bound when one is set.- A sell and a
gtcorgtdorder are sized withquantity. Sendingnotionalon one, or sending bothquantityandnotional, or neither, is refused with422 VALIDATION_ERROR. - A buy sized with
notionalis paid with the cash on the venues it buys on. It doesn’t take a route. POST /v1/orders/previewandGET /v1/markets/{id}/quotetakenotionalthe same way.
Limitations
- Shares stay on the venue that bought them. A sell is placed only on venues that hold the shares.
filled_quantitycomes from the venue’s answer at placement and from later reads. A resting order that later fills completely readsfilled.- An
iocbuy sized withquantityis not placed directly on Polymarket. It goes only to the other venues it can use. When Polymarket is the only one, the order and its preview are refused with400 VALIDATION_ERROR; sendnotionalinstead, or send it asgtc. A buy paid from the other venue can still fill on Polymarket, and never for more thanquantity. - Reading a filled order with
GET /v1/orders/{id}brings its fills intoGET /v1/fills?order_id=, so read the order first when you need its fills right away. 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 after the order readsfilled. If the list is empty, read it again shortly. - An order has no fee field. Its fees are the
fee_usdof its fills inGET /v1/fills. - A live Hyperliquid buy fill shows
fee_usd0, because a Hyperliquid buy pays its fee when the position closes or settles; a sell pays the market’s taker rate.fee_usdisnullwhen the fee was charged in a token Lean cannot value in dollars. - If the venue still has no record of an unconfirmed order ten minutes after placement, the order
is marked
rejectedwithstatus_reason.codeVENUE_UNKNOWN. - An order in
needs_attentionhas a leg Lean cannot settle on its own. It stays live until Lean’s operators resolve it. Do not place it again; read it back later.