> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lean.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Test mode and live mode

> Build against simulated orders with a test key, then switch to a live key to trade for real.

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.

| | Test mode | Live mode |
| - | - | - |
| Key prefix | `lean_sk_test_` | `lean_sk_live_` |
| Orders and fills | Simulated. Nothing is sent to a venue. | Placed on venues and filled for real. |
| Money | None moves. | Real funds in the key's trading account. |
| Balances | Simulated. Each venue starts at 10,000. | The account's real balances. |
| Orders and positions | Test data, kept apart from live data. | Your live data. |
| `livemode` in each successful response | `false` | `true` |

## 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.

```bash theme={"dark"}
export LEAN_API_URL="https://api.lean.xyz"
export LEAN_API_KEY="lean_sk_test_..."
```

[Authentication](https://docs.lean.xyz/authentication.md#create-a-key) shows how to create a key. The
[quickstart](https://docs.lean.xyz/quickstart.md) and the **Try it** button in the
[API reference](https://docs.lean.xyz/api-reference/markets/list-markets.md) 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](https://docs.lean.xyz/orders.md#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](https://docs.lean.xyz/preview.md).
* 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](https://docs.lean.xyz/funding.md#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](https://docs.lean.xyz/stop-losses.md).
* 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](https://docs.lean.xyz/limit-chases.md).
* A test [transfer](https://docs.lean.xyz/transfers.md) 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](https://docs.lean.xyz/api-reference/test-mode/reset-test-mode.md). 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.

```json theme={"dark"}
{
  "success": true,
  "data": { "balances": [ … ], "unavailable": [], "livemode": false },
  "meta": { "requestId": "<request id>" }
}
```

## 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](https://docs.lean.xyz/authentication.md#create-a-key).
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](https://docs.lean.xyz/preview.md) and
   [Orders and idempotency](https://docs.lean.xyz/orders.md#reconcile).

> [!NOTE]
>
> 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"`:

```json theme={"dark"}
{
  "success": false,
  "error": {
    "code": "FEATURE_DISABLED",
    "message": "Live order placement is switched off. Test keys can still place simulated orders.",
    "details": { "reason": "LIVE_TRADING_DISABLED" }
  },
  "meta": { "requestId": "<request id>" }
}
```

A preview with a live key still answers, with `would_submit: false` and a `TRADING_UNAVAILABLE`
warning.

> [!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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.