Orders and command identity
Place, preview and cancel orders with precise values and stable request identities.
Order operations
Placement and cancellation require trade scope or a permitted owner session. Every command is checked against its account binding, account readiness, market status, margin and risk limits.
Load scales, bounds and limits from market metadata before constructing a request. Preview estimates execution and margin using read access, despite using POST. It reserves neither funds nor liquidity, so the subsequent order can have a different outcome.
| Operation | Route | Important behavior |
|---|---|---|
| Preview | POST /v1/orders/preview | Read scope; atom-based request fields |
| Place | POST /v1/orders | Trade scope; Idempotency-Key and clientOrderId required |
| Read one order | GET /v1/orders/{orderId} | Current lifecycle state of an owned order |
| Cancel | POST /v1/orders/{orderId}/cancel | Trade scope; Idempotency-Key; unfilled remainder only |
| Batch place | POST /v1/orders/batch | 1–32 limit orders; independent results in request order |
| Batch cancel | POST /v1/orders/batch/cancel | 1–24 named owned orders; independent results |
Order submission
Order submission
Drag to pan, or use arrow keys when the diagram is focused. Use plus and minus to zoom, and zero to fit. On a touch screen, pinch to zoom.
The trading lifecycle connects the REST command to off-chain execution, account updates and later Canton settlement.
Submit a stable request. Supply clientOrderId and Idempotency-Key with the fields for the selected order variant. The response returns the venue’s orderId. Retain the returned orderId for tracking. Retry placement with the original clientOrderId, Idempotency-Key and request fields.
Track execution. Use command feedback for submission status, then account streams for orders, fills and position changes. Journal and durability information describe off-chain persistence.
Follow settlement. Canton settlement proceeds asynchronously after execution. The diagram shows the responsibilities of each stage; delivery timing between responses and stream events can vary.
Match price and quantity fields to the operation
Placement supports a limit order with decimal-string price and quantity, or a market order sized by quantity or notional using the appropriate request variant. Limit orders can be postOnly. Both kinds can be reduceOnly and can include leverageX and autoClose where the schema permits.
Preview uses quantityAtoms, priceAtoms or notionalAtoms. Convert exact values using the returned market scales. Do not send a preview body's atom field names to placement. Attached autoClose uses takeProfitPriceAtoms and stopLossPriceAtoms; the public contract has no separate trigger arm, cancel or replace operation.
The venue derives IOC behavior for market orders and GTC behavior for limit orders. There is no /v1 timeInForce field. The schema also does not offer an amendment endpoint; cancelling and placing again introduces a period in which the old order can still fill.
{
"accountId": "<account bound to the approved key>",
"marketId": "<marketId from the catalogue>",
"clientOrderId": "<stable identity for this approved logical order>",
"side": "buy",
"orderType": "limit",
"price": "65000.0",
"quantity": "0.001",
"postOnly": true
}Retry without duplicating an order
Choose clientOrderId once per logical order. Choose Idempotency-Key once per logical mutation and retain it across retry attempts. Persist the intended request and these identities before sending, and reuse them with identical fields if the response is lost, a retryable failure occurs or a rate limit asks you to wait. A timeout does not mean that the venue rejected the command.
Do not produce a new clientOrderId because the first call did not answer. Do not change price, size or market under a previous attempt's identity. Read the known order when possible and reconcile account streams before deciding whether a new action is necessary. A placement response uses HTTP 202; inspect the returned order state and confirm subsequent fills through account updates.
Account for partial fills and partial batch success
A cancel body names accountId and marketId; the path names orderId. Exact replay with the same Idempotency-Key returns the original cancellation decision. A later cancel with a new key can return not_found because the order is already terminal. Unknown, terminal, wrong-market and other-account identifiers also return not_found, so do not infer another account's orders from the error.
Each batch entry receives its own indexed result. Accepted siblings remain committed even if another entry is rejected. A batch is not an all-or-nothing transaction. Record and reconcile each result; do not retry the whole batch with fresh identities to repair a single rejection. Cancellation can remain available in restricted market states, but a global engine halt may refuse it. There is no guarantee that a cancellation will win a race with a fill.
Close positions with reduce-only intent
Closing uses a market order in the opposite direction with reduceOnly set, using current position information. It is an order submission and requires trading authority. Reduce-only prevents increasing or flipping the position; it does not guarantee an immediate fill at a particular price.
Read current exposure, inspect a preview when appropriate, retain a stable logical order identity and confirm the resulting fills and position. Stop or re-evaluate if another client changes the account during the process. For automated callers, keep the action within the market, direction, size and limits authorized by the owner. See agent permissions.
Placement request reference
ExternalPlaceOrderRequest has three variants, each requiring accountId, marketId, clientOrderId, side and orderType:
- Market by quantity:: a market order with decimal-string quantity.
- Market by notional:: a market order with decimal-string notional.
- Limit:: a limit order with decimal-string price and quantity; postOnly is optional.
Optional reduceOnly and leverageX apply where supported. Attached autoClose uses takeProfitPriceAtoms and stopLossPriceAtoms as integer atom strings. Fields outside the selected variant are rejected, including a caller-supplied orderId.
HTTP 202 returns ExternalOrderResponse with orderId, status, lastSequence and idempotencyKey. The separate preview request uses atom-based amounts. Consult the place-order reference for the complete schemas.