Start with a test key
Build and test your integration with a test key. You can place, cancel and reconcile as many orders as you like without risking money, and none of them appear in your live account.How test orders behave
- A test order fills against the public order books as soon as you place it. A buy takes the best
ask and a sell the best bid, up to the size shown at that price, when that price is within your
limit and slippage bound. It fills at the book’s price, which can be better than your limit. Its
legshave novenue_order_id. - A buy sized with
notionalwalks the whole public book instead, from the best ask, until the dollars are spent or your limit or slippage bound is reached. It never spends more thannotional, as a live one does. - What doesn’t fill at once follows
time_in_force. Withiocthe rest is canceled. Withfoknothing fills unless all of it can, and the order readscanceled. Withgtcorgtdthe rest stays on the order, which readsopenorpartially_filled. Each time you read the order, the rest fills at its limit price, with no fee, from what the public book then shows at or better than that limit. Agtdorder read after itsexpires_atreadsexpired. - Cancel a resting test order with
POST /v1/orders/{id}/cancel. What filled stays filled. Canceling a test order that has finished returns409 CONFLICT. - The one call works the same way, between Polymarket and Hyperliquid. When a test buy can’t be
paid for from the simulated balance on the venues with a book, Lean pays from the other venue’s
simulated balance and fills on the
venue with the book. The order fills at once at the asks that venue’s public book shows, and
routein the response names both venues, as it would for a live order. When those asks can’t fill the whole size within your limit, the buy is refused with422 VALIDATION_ERROR, as a live one is. No real funds move. The key needs theroutescope, which a Read and trade key made in the app has; without it the buy is refused with422 VALIDATION_ERRORanddetails.reason: "INSUFFICIENT_FUNDS". See Paying from the other venue. - A test sell needs enough simulated shares on one venue. Otherwise it is refused with
422 VALIDATION_ERRORanddetails.reason: "INSUFFICIENT_HOLDINGS". - Your key’s per order and daily limits apply to test orders too.
- Test and live data are kept apart. A test key can’t read a live order, and a live key can’t read
a test order: either lookup returns
404 NOT_FOUND. - A test-key preview’s
route_planis priced over the public order books, as its orders are filled. See Preview. - A test position’s
mark_priceis read the way the Lean portfolio marks live positions: on Polymarket, the market’s last trade, priced for the side held (1 minus the price forno); on Hyperliquid, the venue’s mid for that side’s book.unrealized_pnl_usdis the shares at that price less what they cost. Both arenullwhen the market has no recent trade or the venue has no mid. GET /v1/pnlwith a test key totals unrealized profit and loss exactly as a live key does, over the test positions: a position on a resolved market counts none, and while any other position it counts has no mark,unrealized_pnl_usdandtotal_pnl_usdarenull. Realized profit and loss is what the test fills realized.GET /v1/pnl/historyhas realized profit and loss only for a test key, because past marks of test positions aren’t kept: each point’sunrealized_pnl_usdandtotal_pnl_usdarenull.- A test withdrawal takes simulated cash from the venue’s test balance and moves no real funds. See Withdrawals through the API.
- A test stop loss or take profit is checked against the market and the test account’s simulated shares, and can be listed and canceled, but it never sells. See Stop losses and take profits.
- A test limit chase follows the venue’s public book and fills in simulation once the best price on the other side reaches it. It is brought up to date each time you list or read it, and its fills show in the test account’s positions and balances. See Limit chases.
- A test transfer moves simulated cash between the Polymarket and Hyperliquid test balances. It costs a flat 0.10 USD, its minimum is 2 USD, and it completes as soon as it is executed.
- To start over, call Reset test mode. It clears the account’s simulated orders, positions, withdrawals, transfers, stop losses and limit chases and returns test balances to the starting amount.
Check the mode in code
Every successful response haslivemode in data. Error responses don’t. Check it where your
program would act on money, so a misconfigured key can’t send test orders to production logic or
the other way round.
Go live
When your integration works in test mode:- Create a live key with only the access it needs. A test key can’t be switched to live. Choose Read only for a program that only reads markets.
- Set its per order and daily limits to what the program needs, and no more. Lean refuses any order above them before it reaches a venue. See Authentication.
- Check that the key’s trading account holds enough funds. Use
GET /v1/balances. For Lean to pay for a buy with cash on the other venue, enable trading in the Lean app; otherwise such a buy is refused with422 VALIDATION_ERRORanddetails.reason: "INSUFFICIENT_FUNDS". - To trade on Kalshi or Polymarket US, connect your API key for that venue in the Lean app. A live
order there without one is refused with
403 FORBIDDEN. Test orders don’t need it. - Replace
LEAN_API_KEYwith the live key. Nothing else changes. - Preview before you place each order, and reconcile after it. See Preview and Orders and idempotency.
Live keys trade real money. Lean can pause live trading platform wide, and while it is paused
live orders are refused and test keys keep working.
503 FEATURE_DISABLED
with details.reason: "LIVE_TRADING_DISABLED":
would_submit: false and a TRADING_UNAVAILABLE
warning.