Trade sports markets from code.
One API for canonical sports markets, quotes and orders. Name the outcome you want; Lean finds the venue across Kalshi, Polymarket, Polymarket US and Hyperliquid, prices the route and places the order.
One call to buy
With a test key, nothing real moves:ioc buys by dollar amount only. On a market only Polymarket lists, send
"notional": "25" in place of quantity; see Limitations.
The response is the order. If the book was on Polymarket and the account’s cash on Hyperliquid, or
the other way round, Lean moved the cash and bought on the venue with the book, and route says
so; otherwise route is null:
id:
From a new key to a reconciled trade in five calls
Every step is a plain HTTPS request with a bearer key. The TypeScript SDK and the Rust SDK make each one a typed method.- 01
Create a key
Start with a test key that simulates fills. Each key has its own per order and daily limit.
Authentication - 02
Find a market
List canonical sports markets. You name the outcome; Lean knows the venues.
GET/v1/markets - 03
Place the order
One limit order with your own ID, on any venue and safe to retry on a dropped connection.
POST/v1/orders - 04
Read it back
Read the order by its ID to see its status and fills.
GET/v1/orders/ - 05
Reconcile
Read positions and balances back until the books agree.
GET/v1/positions
Designed for programs that move money
Preview before you trade
POST /v1/orders/preview takes the exact order body and returns the venue, route plan and
refusals, with a read only key.Retries are safe
client_order_id. Sending it again returns the original order, never
a second order.Limits live on the key
One shape everywhere
{ success, data, meta } on success and a stable error code on failure, with a request ID to
quote when you report a problem.Conventions
- Every response uses one envelope:
{ "success": true, "data": …, "meta": … }or{ "success": false, "error": { "code", "message", "details" }, "meta": … }. meta.requestId(also sent as theX-Request-IDheader) identifies the request. Include it when you report a problem.- Prices are decimal strings in dollars per share, strictly between
0and1. - Quantities are shares, as decimal strings. Amounts are USD, as decimal strings.
- Field names are
snake_case. data.livemodein every successful response isfalsefor a test key andtruefor a live key. See Test mode and live mode.
What the API covers
How it works
- Markets cover the full game of a sports match only. Halves, quarters and periods are not listed.
- Lean chooses the venues. A buy is split across eligible venues by best price; a sell takes the best bids across the venues that hold the shares.
- Between Polymarket and Hyperliquid, a buy can pay with cash on the other venue: Lean moves it and buys on the venue with the book, in the same call. Kalshi and Polymarket US orders pay with the cash already on that venue. Shares can’t move between venues.
- Live orders route to Kalshi, Polymarket, Polymarket US and Hyperliquid. Test orders are simulated and never reach a venue.
- Kalshi and Polymarket US are user wide accounts: every trading account of a user shares the same Kalshi and Polymarket US balances and positions, and live orders there use the venue API key the user connected in the Lean app.
- Deposits, transfers, withdrawals and routed orders cover Polymarket and Hyperliquid only.
- Quotes price buys, and sells of shares the account holds.
- Hyperliquid does not cancel resting orders at kickoff. See Orders.