Skip to main content
POST
Place an order

Authorizations

​
X-API-Key
string
header
required

Send the API key in X-API-Key.

Request signing. A key with signing enabled (enabled for the key in its workspace's credential settings, which return the signing secret once; see Sign requests) must also sign every request:

  • X-Timestamp: the current Unix time in seconds, within 300 seconds of the server clock (at most 10 seconds ahead of it on a request that sends X-Nonce).
  • X-Nonce: a fresh random value for each request, 16 to 128 characters of A-Z, a-z, 0-9, - and _ (a UUID fits). Required on a write (POST, PUT, PATCH, DELETE); optional on a read (GET, HEAD).
  • X-Signature: lower-case hex HMAC-SHA256 of the canonical string, keyed with the signing secret's 32 bytes (the secret is 64 hex characters; decode it first).

The canonical string is joined by \n, with no trailing newline: the X-Timestamp value, the X-Nonce value, the upper-case method, the path with its query exactly as sent (/api/v1/orders?limit=1), and the lower-case hex SHA-256 of the exact body bytes (the SHA-256 of an empty body when there is none). A request without X-Nonce (a read) omits the nonce line and signs four lines.

A nonce is accepted once per key: the same nonce again inside the window is refused, whatever the body, so two identical writes in one second each carry their own nonce and both succeed, and a retry signs again with a new nonce. Every API server shares one nonce record, so a nonce accepted by one server is refused by all of them. Rate admission runs first: a rate-limited write (429) does not consume its nonce, and a replay sent while the key is rate limited is answered 429; otherwise a replay spends a rate token and is refused. A read without a nonce changes nothing, so an identical signed read inside the window is admitted again. A write whose window has already passed on the nonce record's clock when its nonce is recorded is refused as TIMESTAMP_OUT_OF_RANGE. If the nonce record cannot be read or written the request is refused with 503 API_KEY_UNAVAILABLE; the nonce may have been consumed, so sign again with a new X-Timestamp and X-Nonce before retrying.

A signing refusal is a 401 AUTH_REQUIRED whose details.reason names the cause: SIGNATURE_REQUIRED (a header is missing), SIGNATURE_INVALID (a malformed header or a wrong signature), TIMESTAMP_OUT_OF_RANGE, NONCE_REQUIRED (a write without X-Nonce), NONCE_INVALID (a malformed or repeated X-Nonce header), SIGNATURE_REPLAYED (the nonce was already accepted). SIGNATURE_PREDATES_RESTART and 429 REPLAY_WINDOW_FULL are reserved and not answered today.

Scopes

​
orders_write
api_key
​
orders_write
bearer_auth

Headers

​
X-Workspace-Id
string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

​
Idempotency-Key
string | null

Makes a retry safe. Required for API keys (a missing key answers 400 IDEMPOTENCY_KEY_REQUIRED); optional for signed-in members. 1 to 255 bytes, unique per order you mean to place; a UUID is a good choice. A retry with the same key and the same body, from the same credential's owner in the same workspace within 24 hours, returns the first answer and never places a second order. The same key with a different body answers 409 IDEMPOTENCY_CONFLICT; another principal's key answers 403 IDEMPOTENCY_AUTHORITY_REQUIRED. A retry that arrives while the first request is still running waits for it, and answers 409 ORDER_IN_PROGRESS (with Retry-After) if it is still running after 30 seconds. Refusals are not stored: after one, fix the request and send it again with the same key or a new one.

Body

application/json

The strict order body: name a held quote and supply only the approval or evidence it asks for.

​
quoteId
string
required

The held quote's id (q_ and a ULID), as POST /quotes returned it.

​
clientOrderId
string | null

Caller reference, 1–64 ASCII letters, digits, underscores or hyphens. Unique in this workspace while the order is non-terminal; independent of Idempotency-Key.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9_-]+$
​
continuesOrderId
string | null

The earlier multi-leg order this one finishes ("Finish this trade", metadata.continuesOrderId). The order path refuses it unless that order is asking its taker to finish and this order spends exactly the funds it left. Protocol quotes only.

​
funding
null | enum<string>

depositFirst on a fiat venue card whose LP balance is short. Instead of refusing FUNDING_SHORTFALL, the order records the person's consent to trade the card's exact debit at no less than its receipt floor once their bank deposit is credited; nothing is sent to the venue now. Absent is today's order. Human only.

Available options:
balance,
credit,
depositFirst
​
fundingDepositId
string<uuid> | null

The Treasury payout that topped up this card's venue account from one of the workspace's company wallets (the payoutId from POST …/treasury/payouts), recorded as what funded the trade. It must exist in this workspace, pay into this card's venue account from a company wallet in the card's debit asset, of at least the card's debit amount, and have completed; a deposit still awaiting approval, in flight or partly done refuses (FUNDING_DEPOSIT_NOT_CREDITED). One deposit funds one order (FUNDING_DEPOSIT_ALREADY_USED) until that order ends without a fill. A resumed order (one naming tradePreparationId) that omits it keeps the deposit its preparation already names. Only with funding absent or set to balance. Venue cards only.

​
minReceive
null | string

The least the person accepts to receive, in receive-Asset units. Required when the quote's minReceiveRequired is true. Other venue cards may accept it as an explicit execution bound; protocol quotes refuse it.

Example:

"10000"

​
ownerAuthorization
null | object

The pay wallet owner's approval, when the held binding pays from an embedded wallet (personal or organisation). The server names the wallet from the binding; this carries only the owner's factor: the hosted approval preflight prepared (walletAuthorization.authorizationId), or an operation-bound RPC factor. Exclusive with signature. Protocol quotes only.

​
priceProtectionBps
integer<int32> | null

Protocol price protection in basis points (1..=1000). May tighten, but never loosen, the held quote's protection without requesting a new price.

Required range: x >= 0
​
settlementWindowId
string<uuid> | null

The settlement window the trader consents to on a quote that carries a settlement window (a delayed-settlement venue trade). Absent, the quote's own window is the consent. After a 409 SETTLEMENT_WINDOW_CHANGED, resend the same quote with this set to details.currentWindow.windowId from that refusal. Refused on a quote that settles immediately (SETTLEMENT_WINDOW_NOT_APPLICABLE).

​
signature
string | null

The taker's signature over the quote's next.sign.typedData; required exactly when next was sign.

​
sourceAuthorizationId
string | null

An authorization this server issued at preflight for this quote's source leg (the native-Solana source permit, a programmable execution's key). Protocol quotes only.

​
sourceTransaction
string | null

The hash (EVM) or signature (Solana) of a source transaction the member's wallet already broadcast on the quote's pay chain (a route's source, a programmable execution, or a relayed source answered as awaiting finality). The order registers it and never broadcasts again; the server verifies it on chain. Protocol quotes only.

​
stepUpProof
string | null
write-only

A trade_authorization step-up proof for a venue card, bound to the confirmation key the refusal's stepUp names (MFA_STALE, STEP_UP_REQUIRED); the quote stays held for this retry. Ignored for a protocol quote.

​
tradePreparationId
string<uuid> | null

A venue trade this member already prepared on the quote's venue connection (for example one a Treasury review has since approved), so the order continues that preparation instead of preparing a new one. It must be the caller's, in this workspace, on the held quote's connection, with bounds that cover the held quote. Venue cards only.

​
travelRule
null | object

The Travel Rule data the member supplies for this transfer (metadata.travelRule). Protocol quotes only.

Response

Order created: a tagged QuoteOrderResponse (advancedTrade or basicTrade). A Basic trade on an on-chain venue (for example Uniswap v3, paid from an organisation wallet) answers 200 as soon as the order is durable, with status: working, before its wallet signs: signing and broadcast run after the answer. Read the order (GET /orders/{orderId}) or subscribe to order.updated for its outcome: settled, or unfilled (terminal) with operation.dispatch.outcomeCode: not_sent and notSentReason: ON_CHAIN_UNSENT when no swap was sent (an approval may have been mined first, spending its network fee). A refusal before the order exists (limits, compliance, funds, authority) still answers here with its code. A refusal found after the order is claimed but before its wallet is asked (the LP relationship, the venue registry, the audit record or your authority changed) also answers here with its own code, and that order reads unfilled with outcomeCode: not_sent.

The Basic venue trade created by POST /orders and read from its saved venue-trade operation. Common order identity and progress fields remain stable; undocumented response fields must be ignored.

New values may be added; treat unknown values as other.

​
deliverTo
object
required

A resolved destination includes observed presentation facts, unlike a request.

New values may be added; treat unknown values as other.

​
fundingAccount
object
required

What backs execution. A link id appears only when money moves through that link.

​
fundingModel
enum<string>
required

What backs execution. A venue declares prefunded or payIn; credit is derived per trade (never declared or chosen): the trade creates or increases a negative position on the venue account, and creditPortion names how much.

New values may be added; treat unknown values as other.

Available options:
prefunded,
payIn,
credit
​
settlement
object
required

The venue's declared terms and, for delayed timing, the account schedule's window.

​
tradingSource
object
required

The exact source selected for a quote, retained through execution and recovery.

New values may be added; treat unknown values as other.

​
fees
object[]
required

The fees actually charged, as recorded: the venue's own fee report, bridge fees, network gas the order's wallet paid, and the platform fee. Never a quoted estimate. A fee whose amount was not reported or could not be read is left out rather than shown as 0, and its kind is listed in unrecordedFees.

​
fills
object[]
required

Each confirmed fill, in execution order. Always present: empty before any fill is confirmed.

​
quotedBuyAmount
string | null
required

The buy amount the executed quote said would land. Null when it is not known (for example before a venue order is dispatched).

​
settledBuyAmount
string | null
required

What actually landed, read from the fill or settlement evidence. Null until it is measured; never the quote carried forward and never 0 for unknown.

​
settlesBy
string<date-time> | null
required

The latest time the order settles, or can no longer execute, under its recorded terms: the signed order's fill deadline, or, on a route, the latest fill deadline every leg commits to (Advanced); the last on-chain step's send-by time (an on-chain Basic swap). Null when no such term is recorded, for example a same-chain DEX swap, whose call carries no deadline.

​
unrecordedFees
enum<string>[]
required

Every fee kind the order incurs whose actual charge is not recorded or could not be read: a venue fee taken inside the price without an amount, a bridge leg's fee, gas the order's wallet spent without a readable receipt, a platform fee billed off the order. Always present; empty only when every incurred charge is in fees. An absent kind with no fees line means nothing of that kind was charged. Open set: clients show an unknown kind generically.

What a fee paid for.

New values may be added; treat unknown values as other.

Available options:
trading,
relayer,
forwarding,
transfer,
network,
platform
​
operation
object
required

A prepared or placed Basic venue trade. Track it by operationId and connectionId; executionStatus describes the trade and settlementStatus describes any subsequent money movement. initialReviewDisposition is the original planning verdict, not current approval. Only the documented fields are part of the integrator contract; undocumented fields may be sent and must be ignored.

​
orderId
string
required

The operation identifier accepted by GET /api/v1/orders/{orderId}.

​
status
enum<string>
required

Open public lifecycle vocabulary shared by both order kinds. States may be skipped; act on terminal, not on a particular sequence.

New values may be added; treat unknown values as other.

Available options:
pending,
working,
filled,
settled,
unfilled,
cancelled,
failed,
refunded,
reviewRequired,
outcomeUnknown,
refused
​
statusUrl
string
required

Where to read this order (GET), with the orders_read API-key scope.

​
terminal
boolean
required
​
kind
enum<string>
required

New values may be added; treat unknown values as other.

Available options:
basicTrade
​
creditCheck
null | object

The credit decision the funding was derived from: point-in-time evidence, never a reservation or dispatch authority. Present exactly when creditPortion is.

​
creditPortion
null | object

A credit trade's exact credit portion: the part of the debit, in the debit asset, that creates or increases a negative position (the rest is spent from positives). Present exactly when fundingModel is credit.

​
creditReservation
null | object

The firm ask's combined cash and credit hold on a credit venue account, held until the quote expires or its order adopts it. Absent on indicative cards.

​
payIn
null | object
​
clientOrderId
string | null

Caller reference supplied when this order was placed.

​
next
object

The one action the caller takes next; later legs run under the order.

New values may be added; treat unknown values as other.

​
quoteId
string | null
​
requestId
string | null
​
settlementCarriedInto
null | object

The later window the trade's amounts were netted into, which it now settles in by that window's settlesBy. Absent when nothing was netted.

​
settlementState
null | enum<string>

Where the filled trade's settlement stands, beside its terms in settlement: settled at once for an immediate venue, a waiting or edge state while a delayed window settles. Absent before the fill and on a trade recorded without settlement terms.

Available options:
settled,
awaitingWindow,
awaitingPayment,
partiallySettled,
overdue,
disputed,
failed,
inTransit
​
settlementStatement
null | enum<string>

Whether the statement of the window the trade settles in is out: issued, pending or failed. Absent with settlementState, and on a trade that settles without a window.

Available options:
pending,
issued,
failed