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

# Preview

> Preview an order without placing it: where it would go, what it would cost, and whether it would be refused.

`POST /v1/orders/preview` takes the exact body of `POST /v1/orders` and answers what that request
would do. It reserves and places nothing, so a `read` key can call it.

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/orders/preview" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "bot-2026-10-29-0001",
    "market_id": "'"$MARKET_ID"'",
    "action": "buy",
    "quantity": "5",
    "limit_price": "0.50",
    "time_in_force": "ioc"
  }'
```

```json theme={"dark"}
{
  "success": true,
  "data": {
    "market_id": "mkt_...",
    "action": "buy",
    "quantity": "5",
    "limit_price": "0.50",
    "time_in_force": "ioc",
    "execution": {
      "venue": "hyperliquid",
      "ticker": "<venue ticker>",
      "side": "yes",
      "notional_usd": "2.5",
      "max_slippage_bps": 100,
      "executable_quantity": "5",
      "expected_average_price": "0.47",
      "legs": [
        {
          "venue": "hyperliquid",
          "ticker": "<venue ticker>",
          "side": "yes",
          "quantity": "5",
          "notional_usd": "2.5",
          "expected_fill_quantity": "5",
          "expected_average_price": "0.47",
          "expected_fee_usd": "0",
          "expected_resting_fee_usd": "0"
        }
      ]
    },
    "would_submit": true,
    "route_plan": { "expected_total_usd": "2.35", "max_total_usd": "2.5", "legs": [] },
    "route": null,
    "warnings": [],
    "livemode": true
  },
  "meta": { "requestId": "<request id>" }
}
```

| Field | Meaning |
| - | - |
| `execution` | Where the order would be placed. `null` when it would be refused before reaching a venue. |
| `execution.venue`, `ticker`, `side` | The one venue order. `null` when the order would be split; read `legs` instead. |
| `execution.legs` | One entry per venue order: `venue`, `ticker`, `side`, `quantity`, `notional_usd`, and the expected fill quantity, average price and fee. `expected_fee_usd` prices each expected fill at the taker rate in the market leg's [`fees`](https://docs.lean.xyz/markets#fees), and is the authoritative fee for the order. `expected_resting_fee_usd` is the maker fee on the part a `gtc` or `gtd` leg would rest, as if it all filled at the leg's `limit_price`, and `0` when nothing rests. A buy is split across eligible venues by best price; a sell takes the best bids across the venues that hold the shares, up to what each venue holds. |
| `execution.notional_usd` | `quantity × limit_price` before fees, and the amount checked against your key's limits. For a buy sized with `notional`, `quantity` and `limit_price` are the shares and worst price that amount reaches on the books, so this is never more than `notional`. Fees come on top: `route_plan.max_total_usd` is the most the order can cost with them. For an order that would take a `route`, `route.notional_usd` is checked instead. |
| `execution.max_slippage_bps` | The slippage bound the order would use: the body's `max_slippage_bps`, or the account's, or `null` when neither sets one. |
| `execution.executable_quantity` | What the books would fill at once across every leg, as last read. |
| `execution.expected_average_price` | The expected price per share across those fills. `null` when nothing would fill at once. |
| `route` | The route `POST /v1/orders` would take: `funding_venue` pays for the buy with its cash and `execution_venue` buys it. `null` when the order would be paid for on the venue it buys on, or refused. With `best_price`, it is set when the route would cost less in all. It carries the route's `notional_usd` and itemized `costs`, as on the placed order. See [Paying from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue) and [Best price across venues](https://docs.lean.xyz/orders.md#best-price-across-venues). |
| `route_plan` | The quote for the same quantity at your limit: the expected (`expected_total_usd`) and worst (`max_total_usd`) cost. Its legs are the ones the order would place. When the order would take a `route`, it prices that route, with the route's costs in `network_cost_usd`. `null` when routing can't plan the order. |
| `would_submit` | `false` when `POST /v1/orders` would refuse this body. |
| `warnings` | Why it would be refused, or what might limit the fill. |

When the trading account can't trade on any venue that lists the market, for example because that venue is not available in your region, the preview answers with the same `403` error that `POST /v1/orders` and the quote return. When a venue has stopped trading the market, the preview answers `409 CONFLICT` with `details.reason: "MARKET_NOT_TRADABLE"`, and when a venue can't be read, `503 UPSTREAM_ERROR`, as the quote does. A Polymarket US market whose book Lean has not loaded yet also answers `503 UPSTREAM_ERROR` with `Retry-After`; send the same preview again after that time.

## Warnings

| `warnings[].code` | Blocks the order | Meaning |
| - | - | - |
| `ORDER_NOTIONAL_LIMIT` | Yes | Above the key's per order limit. |
| `DAILY_NOTIONAL_LIMIT` | Yes | Would take the key or its account past the daily limit. |
| `VENUE_NOT_ALLOWED` | Yes | The trading account does not allow orders on a venue the order names, or on any venue listing this market. |
| `BELOW_VENUE_MINIMUM` | Yes | Below the minimum of every venue that could place it. |
| `INSUFFICIENT_FUNDS` | Yes | The trading account cannot pay for the order on any venue that could place it, and Lean cannot [pay from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue). When it can, the preview shows that in `route` instead and `would_submit` is `true`. |
| `INSUFFICIENT_HOLDINGS` | Yes | A sell for more shares than the trading account holds. |
| `INSUFFICIENT_DEPTH` | Yes | An `all_or_none` order the books can't fill in full within the slippage bound. |
| `POST_ONLY_WOULD_CROSS` | Yes | A `post_only` order would trade at once against the books. |
| `NO_EXECUTABLE_VENUE` | Yes | No venue can place this market today. |
| `CLIENT_ORDER_ID_USED` | Yes | The ID is taken. The order would be answered as a replay of the existing one. |
| `TRADING_UNAVAILABLE` | Yes | The key or its account is paused, or the key is a live key and Lean has paused live trading platform wide. |
| `ROUTE_LIMITED` | No | At this limit, the books or the trading account cover only part of the quantity. |
| `ROUTE_UNAVAILABLE` | No | No route plan: routing is off or no route can take the order. |

## Preview several orders

`POST /v1/orders/preview-batch` takes up to 25 bodies of `POST /v1/orders` in `orders` and
previews them all at once, so the call takes about as long as the slowest preview. Like the single
preview it places nothing, needs only a `read` key, and counts once against the key's rate limit.

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/orders/preview-batch" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "client_order_id": "bot-2026-10-29-0001",
        "market_id": "'"$MARKET_ID"'",
        "action": "buy",
        "quantity": "5",
        "limit_price": "0.50",
        "time_in_force": "ioc"
      },
      {
        "client_order_id": "bot-2026-10-29-0002",
        "market_id": "mkt_unknown",
        "action": "buy",
        "quantity": "5",
        "limit_price": "0.50",
        "time_in_force": "ioc"
      }
    ]
  }'
```

```json theme={"dark"}
{
  "success": true,
  "data": {
    "results": [
      {
        "status": 200,
        "preview": { "market_id": "mkt_...", "would_submit": true, "warnings": [], "livemode": true },
        "error": null
      },
      {
        "status": 404,
        "preview": null,
        "error": { "code": "NOT_FOUND", "message": "Market not found" }
      }
    ],
    "livemode": true
  },
  "meta": { "requestId": "<request id>" }
}
```

`results` has one entry per body, in the order you sent them. `preview` is what
`POST /v1/orders/preview` answers for that body, shortened here; it has every field described
above. When the single preview would answer with an
error, `preview` is `null` and `status` and `error` carry that error's HTTP status, `code`,
`message` and `details`, so one body that can't be previewed does not fail the others. A body that
fails validation, or more than 25 bodies, refuses the whole call with `400`.

Each body is previewed on its own. The limits and holdings checks of one body do not count the
others, so a set of orders that each pass can still go past a limit together.

> [!NOTE]
>
> A preview is a snapshot. Prices and balances can change before you place the order. The daily
> limit is read but not held, so an order placed in between can still take the room a preview saw.


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