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

# Preview before you trade

> See the fill, the fees and the resulting position before placing an order.

`POST /v1/orders/preview` runs an order without placing it. It takes the same body as placing an order, and nothing is recorded or sent. Use it to:

* check an order is valid, and collect every problem in one call;
* see what it would cost and how far the book would move;
* show a person the outcome before they approve it.

## A preview

```bash theme={"system"}
curl https://tradingapi.dev/v1/orders/preview \
  -H "Authorization: Bearer $TRADINGAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"market": "BTC", "side": "buy", "type": "market", "value": "5000.00"}'
```

```json theme={"system"}
{
  "object": "order_preview",
  "valid": true,
  "order": {
    "market": "BTC",
    "side": "buy",
    "type": "market",
    "requested_value": "5000.00",
    "reduce_only": false,
    "size": "0.0592",
    "price": null,
    "price_limit": "84430"
  },
  "estimate": {
    "average_fill_price": "84018.2",
    "price_impact_bps": "1.0",
    "value": "4973.88",
    "fee": "7.212126"
  },
  "position_after": { "direction": "long", "size": "0.0692", "entry_price": "83938.1", "value": "5814.06" },
  "account_after": { "available": "331.27" },
  "notes": [],
  "errors": []
}
```

* **`order`** is the order as it would be sized now.
* **`estimate`** walks the current order book: the average price you would get, how far that is from the mid price in basis points, the value that would fill, and the fee.
* **`position_after`** and **`account_after`** are where you would stand if the order filled as estimated.

An estimate is not a quote. The book moves, so the real fill can differ.

## When the order would be refused

A preview answers `200` for any JSON body. If the order would be refused, `valid` is `false`, and `errors` lists every reason at once, with the same error objects placing it would return:

```json theme={"system"}
{
  "object": "order_preview",
  "valid": false,
  "order": null,
  "estimate": null,
  "position_after": null,
  "account_after": null,
  "notes": [],
  "errors": [
    {
      "type": "permission",
      "code": "key_order_limit_exceeded",
      "message": "This key may place orders of up to $250.00; this one is $5,000.00.",
      "param": "value",
      "hint": "Send a value of at most $250.00, or raise the key's limit on the account page.",
      "details": { "max_order_value": "250.00", "value": "5000.00" },
      "errors": [],
      "retryable": false,
      "doc_url": "https://docs.tradingapi.dev/api-reference/errors#key_order_limit_exceeded"
    }
  ]
}
```

The preview checks everything placing the order would: the fields, the market's rules, your key's limits and your balance. It does not use any of your key's daily budget.

## Asking a person first

A preview makes a simple approval step. Show the person the order and its estimate, and place it only when they approve:

```python theme={"system"}
preview = post("/orders/preview", body)
if not preview["valid"]:
    report([e["message"] for e in preview["errors"]])
elif approve(f"Buy {preview['order']['size']} BTC for about ${preview['estimate']['value']}?"):
    order = post("/orders", {**body, "client_order_id": new_id()})
```

The order is sized again when it is placed, at the price at that moment, so its size can differ slightly from the preview's.