Skip to main content
Place an order against an account, follow it until it fills, and cancel it if it’s still working. One order can book into a container account, into a single segregated account, or be split across several.

What’s available

Trading needs an API key with the Execute trades permission for placing and canceling, and Read trade activity for reading orders back. The account must be enabled for trading. In the sandbox, which pairs are tradable depends on the testnet assets enabled for your organization.

How it works

1

You submit an order

POST /v4/accounts/{accountId}/orders with the symbol, side, quantity, order type, and your own externalId. The 201 returns the order’s id. That’s acceptance, not execution.
2

The order executes asynchronously

A MARKET order fills what it can right away, and any remainder is canceled; one that fills nothing reads EXPIRED. A LIMIT order rests until it fills, expires, or you cancel it. Stop and take-profit orders stay dormant until their trigger price.
3

You poll the order

GET /v4/accounts/{accountId}/orders/{orderId} returns the full state: status, filled quantities, average price, and fees. Webhooks are coming soon.

Where an order books

The accountId in the path can be a container account or a segregated account. IDs are globally unique, so the API recognizes which you sent. That gives three ways to place an order:
  1. Into an omnibus account: pass the omnibus ID, omit allocations.
  2. Into one segregated account: pass that account’s ID, omit allocations. Works under either container type.
  3. Split across segregated accounts: pass the container’s ID and an allocations list. Each entry names a segregated account’s ID (the subaccountId field) and a quantity, and the quantities must sum to the order’s quantity.
Sending allocations with a segregated account’s ID in the path is rejected with INVALID_ALLOCATION.

Order types

Set orderType in the body. It defaults to MARKET. Stop orders trigger when the market moves against the position: at or below triggerPrice for a SELL, at or above for a BUY. TAKE_PROFIT_LIMIT triggers the other way. A price field the order type doesn’t use is rejected.

Time in force

Set timeInForce to control how long the order stays active. It defaults to GTC, except for MARKET orders, which always run as IOC. Two rules to know up front:
  • A MARKET order accepts timeInForce omitted or IOC. Any other value is rejected.
  • currency says which leg of the symbol quantity is in. For FOK orders, a BUY must use the quote currency (USD for BTC-USD, as in “buy $15,000 of BTC”) and a SELL must use the base currency (“sell 1.5 BTC”). Otherwise the order is rejected with INVALID_CURRENCY_FOR_FOK. Other time-in-force values accept either leg.

Order status

Quantities always satisfy filledQuantity + remainingQuantity + canceledQuantity = quantity, in units of currency. The other leg is reported as counterQuantity (before fees) and counterQuantityAllIn (net of fees), with avgPrice and avgPriceAllIn in the quote currency.

Integration steps

Step 1: Place an order

POST /v4/accounts/{accountId}/orders

Market buy into an omnibus account

Buy $15,000 of BTC. The order is IOC, so currency is the quote currency.
The 201 means the order was accepted, not filled. The Location header carries the path of the order. Look it up to see its execution state.

Limit sell from a segregated account

Sell 1.5 BTC at $65,000 or better, valid until a date. The path is the segregated account’s ID, so no allocations.
Request body

Sell allocated across two segregated accounts

Sell 1.0 BTC from the container, booking 0.6 and 0.4 into two accounts. The first allocation also retires a tax lot. The order is FOK, which spec lots require.
Request body
Timed out placing an order? Don’t retry with a new externalId, you might trade twice. Retry with the same Idempotency-Key to get the original result, or find the order with GET /v4/accounts/{accountId}/orders?externalId={yourId}, which returns at most one accepted order.

Rejections

A request that breaks a business rule returns 400 (or 409 for a duplicate externalId) with a message of the form <rejectCode>: <detail>. A request that fails schema validation returns 400 with the validator’s message and no code. Codes you’ll want to handle: INSUFFICIENT_BALANCE, INSUFFICIENT_LIQUIDITY, DUPLICATE_ORDER, INVALID_CURRENCY_FOR_FOK, INVALID_ALLOCATION, and ACCOUNT_DISABLED_FOR_TRADING. The Order schema in the reference lists every code.

Step 2: Get an order

GET /v4/accounts/{accountId}/orders/{orderId} The ID in the path picks the view:
  • Container ID: quantities, fills, and fees are totals for the whole order. If the order was allocated, allocationCount is present.
  • Segregated account ID: quantities, fills, and fees cover only that account’s share, and subaccountId (the segregated account’s ID) and allocationId are present. Any account the order was allocated to works, not just the ID it was placed with. Shares are pro rata, so avgPrice is the same in both views.
quantity here is 0.6, this account’s share of the 1.0 BTC order above.

Step 3: List orders

GET /v4/accounts/{accountId}/orders lists orders, most recently submitted first. With a container ID you get the account-level view. With a segregated account’s ID you get that account’s view of orders placed into it directly plus container orders allocated into it. Filter with externalId, symbol, status, submittedAfter, and submittedBefore. Page with limit and after.

Step 4: List allocations

GET /v4/accounts/{accountId}/allocations lists every booking of an order into a segregated account across all the container’s orders, each in the segregated account view. An order allocated to three accounts appears three times. An order placed directly into a segregated account appears once. Orders booked at the omnibus level don’t appear. Use orderIds to page through one order’s allocations after seeing allocationCount on it:
The path must be a container’s ID. A segregated account’s ID is rejected with INVALID_ACCOUNT. For one segregated account’s orders, use GET /v4/accounts/{accountId}/orders with its ID instead.

Step 5: Cancel an order

POST /v4/accounts/{accountId}/orders/{orderId}/cancel Cancellation is asynchronous. A 200 means the request was accepted. The order moves to CANCELING, then CANCELED or PARTIALLY_CANCELED. Poll the order to see which.
  • Use the ID the order was placed with. Canceling affects the whole order, so it isn’t available through an account the order was merely allocated to.
  • Canceling an order already in CANCELING succeeds again.
  • Orders in a final state, and orders that execute immediately (FOK, IOC, and every MARKET order), are rejected with ORDER_NOT_CANCELABLE.