Preview before you trade

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

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"}'

{
  "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:

{
  "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:

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.

Get started

Concepts

Guides

Preview before you trade

A preview

When the order would be refused

Asking a person first

​A preview

​When the order would be refused

​Asking a person first

A preview

When the order would be refused

Asking a person first