Skip to main content
These examples use two environment variables:
LEAN_API_URL is the Lean API. Test and live keys use the same URL; the key decides the mode. Start with a test key: orders and fills are simulated and no money moves. To create a key, sign in to Lean, open Settings (the gear) and choose API. Authentication explains its limits, and Test mode and live mode shows how to switch to a live key when you’re ready.
1

Find a market

Pick a market whose legs include one with tradable: true, and keep its id:
Markets and IDs explains each field.
2

Place the order

One call places the order. Lean picks the venues among Kalshi, Polymarket, Polymarket US and Hyperliquid. If the book is on Polymarket and the account’s cash on Hyperliquid, or the other way round, it moves the cash and buys on the venue with the book:
Polymarket takes 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. A test order fills at once at the best price on the book, up to the size shown there and within your limit:
route is null when the order was paid for on the venue it bought on, which is always the case on Kalshi and Polymarket US. When Lean paid with cash from the other venue, its funding_venue names the venue the cash came from and its execution_venue the venue it bought on, with the route’s notional_usd and costs. See Paying from the other venue.
An accepted response is not a fill. Read status and filled_quantity, and confirm them with the steps below.
3

Read it back

Use the id from your own response. If the response never arrived, look the order up by client_order_id instead: GET /v1/orders?client_order_id=bot-2026-10-29-0001.
4

Reconcile

See Orders and idempotency.

Quote and preview first

Before you trade live, check what an order would do. Neither call places or reserves anything.
Quote again after expires_at. See Preview. A preview checks the order against the cash on the venues that could place it. When Lean would pay from the other venue, route names both venues and would_submit is true. A blocking warning means the order would be refused.

Try it in the API reference

Every page under API reference has a Try it button that sends a real request with your key and shows the response.
  1. In Lean, open Settings (the gear), choose API, and create a test key with Create API key. Keep the Test mode and Read and trade access.
  2. Open List markets and click Try it.
  3. Under Server, set baseUrl to your LEAN_API_URL, without /v1.
  4. Under Authorization, paste your test key. The playground adds Bearer for you.
  5. Click Send, then copy a market id from the response.
  6. Open Create an order and send it. The body fields start filled with an example; replace market_id and set your own client_order_id.
  7. Copy the order id from the response, and read it back with Get an order.
The key decides the mode. With a test key, Send on Create an order simulates the order. With a live key, it places a real order against the key’s trading account. Use a test key while you experiment.
Each page also shows the request as cURL, Python and JavaScript, with example responses for success and for each error status.

Using TypeScript

The TypeScript SDK runs these same steps with typed methods: npm install @leanxyz/api-sdk, then listMarkets, previewOrder, createOrder and getOrder with the same LEAN_API_URL and LEAN_API_KEY.

Using Rust

The Rust SDK runs the same steps as async methods: add lean-api-sdk from crates.io with Tokio, then list_markets, preview_order, create_order and get_order with the same LEAN_API_URL and LEAN_API_KEY.

Python