Skip to main content
Order entry needs an API key with the Trade permission (reads need Read). See Authentication for how to get one. Every order is a limit order on one market (window), on the outcome you choose.
Orders are real money. A live trade key trades your account’s cash within the key’s limits.

Place an order

201 Created
The response is the order as the book holds it after your request: a buy that crosses the book comes back already part- or fully filled (fill_count, average_fill_price, fees_paid). Only the taker side of a fill pays a fee. Fills against your resting order are free and earn a maker rebate: see Fees and maker rebates. A buy holds cash while it rests: the price plus the most a fill could cost in fees, per contract. The hold is released the moment the order fills at a better price, is cancelled, or the window closes. GET /portfolio/balance shows what you can spend right now.

Retrying safely with client_order_id

Networks drop requests. client_order_id makes a retry safe:
  • Same id, same order → you get back the order already placed. Never a second one.
  • Same id, different order → 409 IDEMPOTENCY_CONFLICT.
So when a request times out, or answers 503 EXCHANGE_UNAVAILABLE, resend it with the same client_order_id — or look it up with GET /portfolio/orders?client_order_id=…. Never retry with a new id: if the first request did reach the book, a new id places a second order. Ids are 1–64 characters (letters, digits, . _ : -) and unique per account, across all your keys.

Order status

Cancel

Cancels are never rate limited, so you can always pull your orders. Cancel-all covers orders you placed through the API. To have them pulled automatically if your program loses its connection, turn on cancel on disconnect.

Many at once (batch)

A quoter posts a ladder of levels, not one order. POST /portfolio/orders/batch places up to 20 orders in one call and DELETE /portfolio/orders/batch cancels up to 100 by id. Items run in the order you send them, and each answers for itself: an order, or an error with the same codes as the single-order routes. One refused item never fails the rest, so always read every result.
Each placed item costs one unit of your key’s order budget (10 per second, bursts of 20): an item past the budget is answered RATE_LIMITED in place and the ones before it stand. Cancels in a batch are free, like every cancel. The idempotency rules are unchanged — resend a batch with the same client_order_ids and you get the same orders back, never duplicates.

Your orders, positions, fills and balance

To have orders, fills and positions pushed to you instead, use the websocket’s private channels. Winning contracts settle automatically after the window closes; the payout lands in your account’s cash.

Server timestamps

Every REST response carries the server’s own timestamps as headers, in epoch milliseconds on our clock. Subtract them from your own send and receive times to split a round trip into network, queue and matching-engine time. UpDown-Queued-Ms and UpDown-Engine-Done-Ms appear only on orders and cancels that reached the book. A batch reports its first item’s queue time and its last item’s answer. A read, or a request refused before the book (a bad body, an unknown order, RATE_LIMITED), carries only UpDown-Received-Ms and UpDown-Sent-Ms. An order or cancel that timed out and was withdrawn from the queue before the engine took it carries UpDown-Queued-Ms but no UpDown-Engine-Done-Ms.

Limits

Three layers apply to every order, and the tightest wins:
  1. Your key’s limits — max order, max per day, max resting orders per market, which series. Trade keys start at $20 per order** and **$500 per day unless you set others. GET /account shows them, and daily_used_usd shows how much of the day’s limit is used. The daily figure counts what filled in the last 24 hours plus what is resting right now, plus the stakes of any Boost orders the key placed in the last 24 hours. A cancelled order never counts, so a quoter that places and pulls all day only uses the limit with real fills and live quotes.
  2. Your account’s limit — a cap on how much you can have at risk across all open windows at once.
  3. The market’s limit — a cap on all users together in one window.
Going over any of them answers 400 LIMIT_EXCEEDED with a message saying which. New orders are also limited to 10 per second per key (bursts of 20); see Rate limits.

Before your first order

  • Your account must have accepted the current Terms of Service and allowed trading on its wallet (a one-time step in the app). Without them, a buy answers 403 FORBIDDEN saying which.
  • Orders go only to markets on the order book — the ones GET /markets lists. Anything else answers 400 MARKET_NOT_OPEN.
  • Test keys can’t place orders yet: the practice book isn’t open.

Errors