Skip to content
Reef

Orders API

Order mutation routes require X-Client-Id and Idempotency-Key headers (see API Overview). Field validation happens before any durable command acceptance.

POST /api/v1/orders/submit

Section titled “POST /api/v1/orders/submit”
{
  "commandId": "uuid",
  "traceId": "uuid",
  "causationId": "uuid",
  "correlationId": "uuid",
  "actorId": "string",
  "occurredAt": "2026-07-05T14:00:00.000Z",
  "orderId": "uuid",
  "instrumentId": "uuid",
  "participantId": "uuid",
  "accountId": "uuid",
  "side": "BUY | SELL",
  "orderType": "LIMIT",
  "quantityUnits": "10",
  "limitPrice": "99.50",
  "currency": "USD",
  "timeInForce": "DAY | IOC"
}

orderType accepts LIMIT and LIMIT_HIDDEN; market orders are not yet validated at this boundary (see Bot SDK Reference for how the arena adapter handles this today).

POST /api/v1/orders/modify

Section titled “POST /api/v1/orders/modify”
{
  "commandId": "uuid",
  "traceId": "uuid",
  "causationId": "uuid",
  "correlationId": "uuid",
  "actorId": "string",
  "occurredAt": "2026-07-05T14:00:00.000Z",
  "orderId": "uuid",
  "runId": "run-uuid",
  "venueSessionId": "session-uuid",
  "instrumentId": "instrument-uuid",
  "participantId": "participant-uuid",
  "accountId": "account-uuid",
  "quantityUnits": "5",
  "limitPrice": "100.00"
}

POST /api/v1/orders/cancel

Section titled “POST /api/v1/orders/cancel”
{
  "commandId": "uuid",
  "traceId": "uuid",
  "causationId": "uuid",
  "correlationId": "uuid",
  "actorId": "string",
  "occurredAt": "2026-07-05T14:00:00.000Z",
  "orderId": "uuid",
  "runId": "run-uuid",
  "venueSessionId": "session-uuid",
  "instrumentId": "instrument-uuid",
  "participantId": "participant-uuid",
  "accountId": "account-uuid",
  "reason": "string"
}

Cancel and modify require the complete target-order context. The boundary authorizes participantId and accountId against the authenticated principal; the matching engine then compares every routing and ownership value with the canonical target order before mutation. A mismatch is rejected as ORDER_CONTEXT_MISMATCH without changing the order.

POST /api/v1/orders/cancel-by-client-order

Section titled “POST /api/v1/orders/cancel-by-client-order”

Slower resolver path for clients that know their own clientOrderId but do not have the routed venue cancel metadata. The runtime resolves (participantId, clientOrderId) outside the matching hot path, synthesizes the normal cancel body with order, routing, participant, and account identity, then submits it through /api/v1/orders/cancel.

This route is not part of the throughput target. Hot-path cancels should include routing metadata and use /api/v1/orders/cancel directly.

All mutation routes require a non-blank RFC 3339 occurredAt; malformed timestamps are rejected before durable intake.

{
  "commandId": "uuid",
  "traceId": "uuid",
  "causationId": "uuid",
  "correlationId": "uuid",
  "actorId": "string",
  "occurredAt": "2026-07-05T14:00:00.000Z",
  "participantId": "uuid",
  "clientOrderId": "client-order-123",
  "reason": "string"
}

Response Shape

Section titled “Response Shape”

Order command routes return the same result envelope (mirrors SubmitOrderResult in the wire contract — see Wire Contracts):

{
  "outcome": {
    "accepted": { "eventId": "...", "orderId": "...", "engineOrderId": "...", "occurredAt": "..." }
  },
  "executions": [ { "eventId": "...", "executionId": "...", "orderId": "...", "instrumentId": "...", "quantity": {"units": "..."}, "executionPrice": {"nanos": "...", "currency": "..."}, "occurredAt": "..." } ],
  "trades": [ { "eventId": "...", "tradeId": "...", "executionId": "...", "buyOrderId": "...", "sellOrderId": "...", "instrumentId": "...", "quantity": {"units": "..."}, "price": {"nanos": "...", "currency": "..."}, "occurredAt": "..." } ]
}

Or, on rejection, outcome.rejected with { eventId, orderId, code, reason, occurredAt } instead of outcome.accepted.

POST /api/v1/orders/lifecycle-state

Section titled “POST /api/v1/orders/lifecycle-state”

Rebuilds the runtime.order_lifecycle_state projection (open/filled/cancelled order state) used by market-data reads. No request body fields; returns a rebuild-status payload.

Learn More

Section titled “Learn More”