Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A Lean API key, sent as Authorization: Bearer <key>. A test key (lean_sk_test_...) simulates orders and fills with no money; a live key (lean_sk_live_...) trades for real within the key's limits. Every successful response says which mode answered in data.livemode.

Body

application/json
client_order_id
string
required

Unique per API key. Replaying an id returns the original order.

Pattern: ^[A-Za-z0-9_-]{1,64}$
market_id
string
required

A market id from GET /markets, or a venue symbol that names one market: a Polymarket token id, a Hyperliquid book coin (#…, written %23… in a path), or a leg ticker (pm:…, hl:…, pmus:… or a Kalshi market ticker) that lists only this outcome. A symbol that names more than one market, such as a Polymarket condition id, is refused with 400; use the token id or the market id instead. An order named by a venue symbol trades only that listing, so it is refused when venues leaves out the symbol's venue. A buy routed automatically still buys that listing, paid from the other venue. The order is stored under the market id.

Required string length: 1 - 512
action
enum<string>
required
Available options:
buy,
sell
quantity
string

Shares, in 0.01 steps. Send exactly one of quantity or notional. A sell of the whole position, as held or written to two decimals, sells what each venue's increment allows and keeps the rest.

Pattern: ^\d+(?:\.\d+)?$
notional
string

Dollars to spend on an ioc or fok buy, in place of quantity, at most two decimals. The buy walks the books from the best price and never spends more than this before fees; Lean works out the shares. Sells and resting orders are sized with quantity.

Pattern: ^\d+(?:\.\d{1,2})?$
limit_price
string

Worst price per share you accept, in dollars. Required with quantity on a limit order. With notional or on a market order it defaults to 0.99 for a buy and 0.01 for a sell; a market order is then placed 1 cent past the worst price its quantity reaches in the book, tightened by max_slippage_bps when set.

type
enum<string>
default:limit

limit trades at limit_price or better. market trades at once at the best prices: it needs time_in_force ioc or fok, and each venue order is placed 1 cent past the worst price its quantity reaches in the book of that venue. limit_price and max_slippage_bps are optional extra caps on the worst price it accepts.

Available options:
limit,
market
time_in_force
enum<string>
default:gtc

gtc rests until filled or canceled. ioc fills what it can at once and cancels the rest. fok fills the whole order at once or cancels all of it, and is placed whole on one venue: Polymarket, else Kalshi, else Polymarket US, since Hyperliquid has no fill or kill. gtd rests like gtc until expires_at, and is placed on Kalshi, Polymarket and Polymarket US, since Hyperliquid has no order expiry. Polymarket takes an ioc or fok buy only by dollar amount: one sized with notional can fill there, while one sized with quantity goes only to the other venues, and when Polymarket is the only one it is refused with 400 VALIDATION_ERROR, so send it with notional or as gtc. notional needs ioc or fok.

Available options:
gtc,
ioc,
fok,
gtd
expires_at
string<date-time>

When a gtd order expires, as an ISO 8601 time. Required with gtd and refused with any other time_in_force. At least 3 minutes and at most 30 days ahead. Whatever has not filled by then is canceled, and the order reads expired.

max_slippage_bps
integer

Optional extra cap: the furthest each venue order may trade from that venue's own best price, in basis points; overrides the account's max_slippage_bps. Each venue is measured against its own book, not the best price across venues, so venues quoting different prices can each fill. Never looser than limit_price. Without one, a limit order trades to its limit and a market order to 1 cent past the worst price its quantity reaches in the book, as the Lean trading terminal places it.

Required range: 0 <= x <= 10000
all_or_none
boolean
default:false

Refuse the order unless the books, as read, fill the whole quantity within the slippage bound. Needs time_in_force ioc or fok. Best effort: venue orders are placed separately and books can move between the read and the fill, so a partial fill is still possible.

post_only
boolean
default:false

Only rest on the book, never take. Needs time_in_force gtc, cannot take best_price, and is placed on Kalshi, Polymarket US and Hyperliquid, since Polymarket cannot rest post-only. An order that would trade at once against the books, as read, is refused with reason POST_ONLY_WOULD_CROSS, and the venue rejects one that would trade by the time it arrives.

venues
enum<string>[]

Only these venues may fill or fund the order, within the account's allowed venues. A single venue sends the order only there, and the order is refused if that venue can't fill it. Omit to use every allowed venue.

Minimum array length: 1
Available options:
kalshi,
polymarket,
polymarket_us,
hyperliquid
best_price
boolean
default:false

Buy at the best price across venues: when a route across venues that moves cash from another venue would cost less in all than buying where the account's cash is, the buy goes through that route. Needs the route scope. A test key prices a route at the order's limit, so there it wins only when the direct buy's fees cost more. Sells already sell across every venue that holds shares, so this does not change them.

Response

What POST /v1/orders would do with this body and the best route across venues; places and reserves nothing

success
enum<boolean>
required
Available options:
true
data
object
required
meta
object
required