Order entry

Every order command acts on the account your session is bound to and is answered once, in command order. An acknowledgement means the command was admitted, not that an order is working, filled, or canceled: order and execution events report what happens next.

• CreateOrder · template 2 · answered by CommandAck (CREATE_ORDER)
  Retry identity: none; reconcile by clientOrderId.
• CancelOrder · template 3 · answered by CommandAck (CANCEL_ORDER)
  Retry identity: none; a cancel never applies twice.
• ModifyOrder · template 4 · answered by CommandAck (MODIFY_ORDER)
  Retry identity: correlationId.
• CancelAllOrders · template 5 · answered by CommandAck (CANCEL_ALL_ORDERS)
  Retry identity: correlationId, 120 seconds.
• BatchCreateOrders · template 7 · answered by BatchCreateAck
  Retry identity: correlationId, 15 minutes.
• BatchReplaceOrders · template 8 · answered by BatchReplaceAck
  Retry identity: correlationId.
• BatchCancelOrders · template 9 · answered by BatchCancelAck
  Retry identity: correlationId.

Any command can instead be answered with a CommandReject. Field layouts are in the Message reference.

Create an order

CreateOrder submits one order.

A successful create returns a CommandAck with the new public orderId, the symbolId, and resolvedBaseQtyScaled. It also returns submittedMaxQuoteDebitScaled when a quote budget was submitted.

Create-order sizing

Use the CreateOrder layout from the schema for your environment. Set sizingKind and exactly one matching quantity field:

MAX_QUOTE_DEBIT is valid only for BUY Market IOC and BUY Limit IOC. The order spends the whole quote amount at the prices it pays and never more, then ends canceled at its filled quantity (see Order sizing). BASE_QUANTITY is an exact gross base quantity.

Set feeAsset to QUOTE or BASE. BASE is valid only for BUY. A successful create acknowledgement returns resolvedBaseQtyScaled and returns submittedMaxQuoteDebitScaled when a quote budget was submitted.

The SBE command path does not expose order preview. Use POST /v1/orders/preview (ConnectRPC PreviewOrder) when an integration needs a non-mutating account admission check; see Preview order. See Order sizing for quantity fields and acknowledgement semantics.

Retrying a create

CreateOrder has no replay. Resending it, even byte for byte, creates a second order unless the clientOrderId is still reserved, in which case it is rejected with CONFLICT_DUPLICATE_CLIENT_ORDER_ID. That reject carries existingOrderId, the order that holds the ID, when it is known. correlationId does not deduplicate creates.

Use the reject code to decide:

• CommandAck · the order was admitted
  Track it by orderId.
• UNAVAILABLE · the order was not accepted
  Retry with the next seq; if the connection then closes with 1013, reconcile first.
• ORDER_CREATE_OUTCOME_UNKNOWN · the order was sent but not confirmed; it may exist
  Read the order by clientOrderId before deciding to resend; the connection closes with 1013.
• No answer · the connection dropped first
  Read the order by clientOrderId before deciding to resend.

Read an order by its client order ID with GetOrder, which accepts either an order ID or a client order ID. Without a clientOrderId, a lost acknowledgement can leave the outcome unknown. See Client order IDs for retention and reconciliation.

Cancel an order

CancelOrder names the order by exactly one of orderId or clientOrderId; set the other to 0 or empty. symbolId is optional: 0 lets the service resolve the Pair from the order.

The CommandAck returns the orderId whose cancellation was requested. The order can still fill until the cancellation completes; its OrderEvent reports CANCELED or FILLED. A cancellation never applies twice. A cancel of an order that has already ended is rejected with ORDER_ALREADY_TERMINAL, including a repeat of the cancel that ended it; treat it as already done and read the order for how it ended. A repeat sent while the first cancel is still in progress is acknowledged again and changes nothing.

A symbolId that names another Pair than the order's is rejected with ORDER_UNKNOWN and cancels nothing; an order that ended a while ago may instead be reported ORDER_ALREADY_TERMINAL. A clientOrderId keeps naming its order for at least a minute after the order ends, so a later cancel by clientOrderId may be rejected with ORDER_UNKNOWN. Cancel by orderId when you have it. Every cancel, a repeat included, counts against the account's cancel rate limit.

ORDER_CANCEL_OUTCOME_UNKNOWN means the cancel was sent but not confirmed and may still apply. Read the order before retrying. CANCEL_REQUEST_EXPIRED means the cancel expired before it was admitted; send a new one.

Modify an order

ModifyOrder changes the quantity, price, or client order ID of one open order.

Send at least one change. The behaviors:

• AMEND_OR_REPLACE amends the order in place when it can, keeping its orderId and queue priority, and otherwise replaces it.
• AMEND_ONLY amends in place and rejects a change that needs a replacement with MODIFICATION_REQUIRES_REPLACE. A new client order ID always needs a replacement.
• REPLACE_ONLY always cancels the order and creates a successor with a new orderId and reset queue priority.

The acknowledgement's orderId is the order that carries the result: the same ID after an amend, or the successor's ID after a replace. A new total quantity at or below the filled quantity ends the order at its filled quantity and is answered with QTY_AT_OR_BELOW_FILLED.

Keep correlationId and the request body unchanged when you retry, including after reconnecting. Use a fresh correlationId for each new modification. Reusing one with a different body is rejected. ORDER_MODIFY_IN_PROGRESS and ORDER_PLACEMENT_PENDING mean an earlier change or the order's placement has not completed; retry shortly. ORDER_MODIFY_OUTCOME_UNKNOWN means the change may still apply: read the order before retrying.

Cancel all orders

CancelAllOrders cancels every open order of the account that matches its filter:

• symbols: up to 100 positive symbolId values; an empty group matches every Pair, and duplicates are ignored. More than 100 is rejected with BAD_REQUEST.
• side: BUY, SELL, or null (0) for both.
• dryRun: 1 counts the matching orders without canceling them; 0 cancels.
• correlationId: required and nonzero; the cancellation's identity.

The CommandAck for a cancel-all reports matchedOrders, submittedCancels, and failedCancels.

The CommandAck for a cancel-all that is not a dry run lists the canceled orders in its cancelledOrders group: up to 200 orderId and clientOrderId entries, oldest first. When cancelledOrdersTruncated is 1, more orders were canceled than listed; read the remaining open orders over REST or ConnectRPC. listingStatus is INCLUDED on the first answer. Resending the same correlationId and criteria within 120 seconds returns the original counts with an empty list and listingStatus NOT_RETAINED_READ_OPEN_ORDERS, and requests no new cancellations. See Cancel All Orders.

Use a fresh correlationId for each new cancel-all, including after the 120-second window. Each canceled order reports its final state in its own OrderEvent. Cancel-all does not cancel standalone triggers.

Batch commands

Each batch item is admitted or rejected on its own, and each item counts against your rate limit. The batch correlationId is its account-scoped idempotency key: resending the same correlationId and items answers the original per-item results instead of acting again. A batch create is recognised for 15 minutes.

If a batch is answered with UNAVAILABLE, or its acknowledgement never arrives, some items may already be admitted. Resend the same correlationId and items to learn each item's result. Do not assume that nothing changed.

The same correlationId with different items is rejected item by item with CONFLICT_IDEMPOTENCY_KEY_REUSE. The identity is shared with the request_id of the REST and ConnectRPC batch operations, such as POST /v1/orders/batch, but the payloads never match across encodings, so reusing one identity across interfaces is rejected the same way and changes nothing.

A structurally invalid batch, such as one with no items or more than its limit, is rejected as a whole with a CommandReject and does not use its sequence number.

BatchCreateOrders

Up to 20 orders, on any Pairs. Each item has the same fields and rules as CreateOrder. An invalid item is rejected alone; the others proceed. A clientOrderId that is reserved, or repeated within the batch, rejects only its item with CONFLICT_DUPLICATE_CLIENT_ORDER_ID.

BatchCreateAck carries acceptedCount, rejectedCount, and one result per item in request order: status (ACCEPTED or REJECTED), code, orderId, resolvedBaseQtyScaled, submittedMaxQuoteDebitScaled, and existingOrderId for a duplicate client order ID.

ORDER_CREATE_OUTCOME_UNKNOWN on a batch create means every item's outcome is unknown. Resend the same correlationId and items within 15 minutes: decided items return their original results, and the rest are retried without admitting any item twice.

BatchReplaceOrders

Up to 50 modifications on one Pair, named once in the batch's symbolId, each naming a different order. Each item has orderId or clientOrderId, and at least one of newQtyScaled or priceTicks, plus an optional newClientOrderId.

Every item follows AMEND_OR_REPLACE:

• Keeping the price, not raising the total quantity, and keeping the client order ID amends the order in place, with the same orderId and its queue priority.
• A new price, a larger total quantity, or a new client order ID replaces the order with a successor that has a new orderId and reset queue priority.
• A new total quantity at or below the filled quantity ends the order at its filled quantity, with no successor.

To force a replacement, use ModifyOrder with REPLACE_ONLY. A malformed item, a repeated target, or a missing symbolId rejects the whole batch; a missing symbolId answers BATCH_SINGLE_SYMBOL_REQUIRED. An item whose order is on another Pair is rejected alone as ORDER_UNKNOWN; the other items are still processed.

BatchReplaceAck carries status (ADMITTED, PARTIALLY_ADMITTED, or REJECTED), the counts, batchRequestId (the same for every retry of the batch), and one result per item: status, code, action (AMENDED or REPLACED), oldOrderId, and replacementOrderId. After AMENDED, keep tracking oldOrderId; after REPLACED, track replacementOrderId. To read each item's later progress, pass batchRequestId to GetBatchReplaceStatus.

The acknowledgement answers at admission, so an admitted item can still be refused when it is applied, for example a post-only order moved to a price that would cross. The modify then changes nothing: the order keeps its previous price and quantity, and the planned replacementOrderId never becomes an order, so no rejected order appears under it. Treat that ID as planned until order events or reads confirm it. The same holds for a ModifyOrder that replaces its order.

BatchCancelOrders

Up to 50 cancellations, each naming one order by orderId or clientOrderId, with an optional symbolId. BatchCancelAck carries the counts and one result per item: status, code, and the orderId. An accepted item means cancellation was requested; order events report the final state. A cancellation never takes effect twice. A retry answers an item whose order has since ended with ORDER_ALREADY_TERMINAL, or with ORDER_UNKNOWN when it names the order by a clientOrderId that no longer names it.

Not available on this interface

Triggers (stop, take-profit, trailing, TWAP, ladder), attached take-profit and stop-loss legs, cancel-all-after, order preview, and reads are not available over SBE WebSocket. Use REST or ConnectRPC for them, for example POST /v1/triggers and POST /v1/orders/cancel-all-after; their orders still appear in your SBE order and execution events.