Submit an order
Submits an order (orders:trade): the Idempotency-Key is its clientOrderId, the instrument is named by instrumentId or by symbol (instrument), and the owner judges price and qty against it. Answers the queued row, or the refusal the owner’s validation chain reached — the guide.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
On POST /orders the key is the order's clientOrderId: 1 to 36 characters from [A-Za-z0-9._~-], scoped to you at the gateway and to the organisation at the owner. A retry replays or attaches; a key that reaches the owner afresh restates the same order, never a second one. A body clientOrderId may restate it, never contradict it (400).
Request
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
money (a Decimal on the wire): a decimal string on input, encoded at its own scale — the fractional digits sent, trailing zeros dropped, at most 18. The edge consults no reference data: a value finer than its record is the platform's to judge, not the edge's to refuse
a boolean; absent reads false
Refused INVALID_FIELD in v1; ships for 119/120 and derivatives. a boolean; absent reads false
0 = none (MARKET only); LIMIT requires price > 0 — zero and negative refuse INVALID_FIELD (arm 10: the sentinel is never a legal limit price). money (a Decimal on the wire): a decimal string on input, encoded at its own scale — the fractional digits sent, trailing zeros dropped, at most 18. The edge consults no reference data: a value finer than its record is the platform's to judge, not the edge's to refuse; absent, null or "0" = unset (the 0 sentinel)
The client's idempotency key for the order, 1 to 36 US-ASCII characters (a canonical hyphenated UUID fits; the owner refuses empty or longer as INVALID_FIELD — an empty key is no identity). It deduplicates at the platform's edge only, never at the venue: orderId is what the venue sees.
The account's display name within your organization. An alias for accountId: name the account either way, at least one of the two; both stated must agree, else 400 MALFORMED_REQUEST. The edge resolves the name against the accounts this member holds and puts the id on the wire, because a name is the org's to change and a command carrying one would name a different account after a rename. A name no live account of your org holds refuses 422 ACCOUNT_NOT_ACTIVE. An account still being classified has no bound name and is addressable by id alone.
The instrument's platform symbol — refdata's natural key, VENUE@BASE/QUOTE with the product suffix where the venue has one ("OKX@BTC/USDT", "OKX@BTC/USDT:SWAP"). An alias for instrumentId: name the instrument either way, at least one of the two; both stated must agree, else 400 MALFORMED_REQUEST. The edge resolves the symbol against the instruments this member holds and puts the id on the wire; a symbol no instrument here holds refuses 422 INSTRUMENT_NOT_LIVE at the door, the code the orders owner answers to an unheld id. The id is the stable address, the symbol the convenience.
Response
The order as the platform now holds it: on a submit the queued row (or your existing order under the same clientOrderId), on a cancel the row with cancelRequestedAtNs set and the status unchanged — with the answering change's position, the order's ETag and, on a replayed key, Idempotent-Replay.
The accept's consensus time, stamped by the owner — the anchor instructFreshnessNs measures from; carried on the record so a restored snapshot keeps the window. int64 as a decimal JSON string
The edge key echoed; never the venue key.
The oe credential the owner RESOLVED at submit — the org's live canTrade credential for the account's venue, not the account's own read-only credential. The connector's fold filter is credentialId ∈ mine.
Derived from the deduplicated execution set — never from the venue's cumulative; rounded by the owner. money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw
The venue order id once bound (ACKNOWLEDGED or first evidence carrying it); empty until then.
The position as a decimal string — the last change this member had applied, orders and balance readings included.
qty - cumQty at a live status; 0 at any terminal. money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
Owner-stamped.
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw
The transition's cause when one applies (UNKNOWN otherwise); the raw venue leg rides venueCode/venueText. UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
Which trading policy row — the organisation-wide default or a per-instrument one — the validation ran against.
UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict
The submitting user; actors of later commands ride those commands and the envelope's causation, never restamped here.
The last reason triple's text leg; empty when none.
Per-order, monotonic, bumped on every row; a restored snapshot restates the last version. int64 as a decimal JSON string
Derived from the deduplicated execution set (half-even rounding); 0 = no fills. money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw; null when the 0 sentinel means unset
The venue-async cancel window's base: set by CANCEL_REQUESTED, cleared (0) by CANCEL_REJECTED, mooted by terminals; feeds the pending-cancel backstop timer. Consumers answer 'is a cancel in flight' as live status AND nonzero here — there is no PENDING_CANCEL status to watch for. int64 as a decimal JSON string
First INSTRUCTED evidence time; 0 until instructed. int64 as a decimal JSON string
Accounting closure: true if and only if the deduplicated execution set reconciles against the lifecycle (FILLED: the set equals qty; other terminals: the set equals venueCumQty where reported). False keeps the reconcile lane chasing fills — a venue's terminal status stands while this is false. a boolean; absent reads false
a boolean; absent reads false
a boolean; absent reads false
money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw; null when the 0 sentinel means unset
The most recent leg reported for this order, for a merged FIX-style rendering (LastQty/LastPx); 0 = none. On a bust or correction it describes the referenced trade, not the surviving fill, and a report about no leg carries the previous value forward — read cumQty/avgPx, never this pair, for what the set currently stands behind. money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw; null when the 0 sentinel means unset
money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw; null when the 0 sentinel means unset
The base of the venue-side reconcile window, the sibling of cancelRequestedAtNs: set by RECONCILE_REQUESTED, cleared (0) by the venue evidence that answers it. Stored rather than derived from the transition, because a restored snapshot restates every row as SNAPSHOT and a derived window would differ on a warm-started member. Consumers answer 'is a reconcile outstanding' as non-zero here — never by watching for a transition. int64 as a decimal JSON string
The venue's claimed cumulative — the cross-check watermark behind isExecutionsComplete; -1 = never reported. money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value's own scale — every fractional digit that scale states, trailing zeros included; never raw; null when the -1 sentinel means unset
The per-order venue-time watermark; 0 = no venue evidence yet. int64 as a decimal JSON string
Never present since 0.3.3: every money value on this API states its own scale on the wire — a policy amount or cap since 0.3.3, an order's and an execution's since 0.3.2, a balance's since 0.3.1 — so a row is never served raw, whether or not this member holds the asset or instrument it references. Kept, deprecated, so a client generated from 0.3.2 still compiles; it goes at the next major.