Skip to main content
Every API key is either a test key or a live key. The key you send decides the mode. The base URL, the endpoints and the request bodies are the same in both, and both kinds of key use the same trading account. A new key is a test key unless you create it as a live key. A test key never sees or spends the account’s real balances. It sees simulated balances that start at 10,000 on each venue (USD on Kalshi and Polymarket US, pUSD on Polymarket, USDC on Hyperliquid), and test orders draw only on those. Markets and quotes are the same real market data in both modes.

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.
Authentication shows how to create a key. The quickstart and the Try it button in the API reference work with either kind of key.

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 legs have no venue_order_id.
  • A buy sized with notional walks 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 than notional, as a live one does.
  • What doesn’t fill at once follows time_in_force. With ioc the rest is canceled. With fok nothing fills unless all of it can, and the order reads canceled. With gtc or gtd the rest stays on the order, which reads open or partially_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. A gtd order read after its expires_at reads expired.
  • Cancel a resting test order with POST /v1/orders/{id}/cancel. What filled stays filled. Canceling a test order that has finished returns 409 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 route in 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 with 422 VALIDATION_ERROR, as a live one is. No real funds move. The key needs the route scope, which a Read and trade key made in the app has; without it the buy is refused with 422 VALIDATION_ERROR and details.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_ERROR and details.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_plan is priced over the public order books, as its orders are filled. See Preview.
  • A test position’s mark_price is 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 for no); on Hyperliquid, the venue’s mid for that side’s book. unrealized_pnl_usd is the shares at that price less what they cost. Both are null when the market has no recent trade or the venue has no mid.
  • GET /v1/pnl with 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_usd and total_pnl_usd are null. Realized profit and loss is what the test fills realized. GET /v1/pnl/history has realized profit and loss only for a test key, because past marks of test positions aren’t kept: each point’s unrealized_pnl_usd and total_pnl_usd are null.
  • 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 has livemode 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:
  1. 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.
  2. 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.
  3. 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 with 422 VALIDATION_ERROR and details.reason: "INSUFFICIENT_FUNDS".
  4. 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.
  5. Replace LEAN_API_KEY with the live key. Nothing else changes.
  6. 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.
While live trading is paused, a live key can still read markets, quotes, orders, balances and positions, and cancel orders. Placing an order with it returns 503 FEATURE_DISABLED with details.reason: "LIVE_TRADING_DISABLED":
A preview with a live key still answers, with would_submit: false and a TRADING_UNAVAILABLE warning.
A live key places real orders, including from the Try it button in the API reference. Keep test and live keys in separate secrets, and never commit either to source control.