POST /trade
Submits one signed action.
curl -sS -X POST "$API_URL/trade" \
-H 'content-type: application/json' \
-d '{
"action": {
"type": "order",
"market_id": "0",
"side": "bid",
"order_type": "limit",
"tif": "gtc",
"price": "1000.00",
"quantity": "0.0025",
"cloid": "0x11111111111111111111111111111111"
},
"nonce": "1760000000000",
"expires_after_ms": "1760000005000",
"signature": "0x..."
}'Request envelope fields:
action
yes
Public action object. Supported top-level action types are order, cancel, cancelAll, modify, and batch.
nonce
yes
Decimal string u64 Unix millisecond timestamp nonce. Use current Date.now()/Unix ms; if sending multiple requests in the same millisecond for the same signer, increment locally so each signed nonce is unique and monotonically nondecreasing.
agent_epoch
no
Decimal string u64; required only for agent-signed requests. Omit for owner-signed requests.
expires_after_ms
no
Decimal string u64 Unix milliseconds. Expired transactions are rejected during execution.
signature
yes
0x-prefixed 65-byte recoverable secp256k1 signature over the canonical unsigned payload.
Nonce validation is signer-scoped. Execution accepts nonces within the committed block timestamp window (block_timestamp_ms - 2 days through block_timestamp_ms + 1 day), rejects duplicates, and retains the latest 100 consumed nonces per signer. When the retained window is full, a new nonce must be greater than the current minimum retained nonce.
order
Places one order.
type
yes
"order"
market_id
yes
Decimal string market id.
side
yes
"bid" or "ask"; "buy" and "sell" are also accepted aliases.
order_type
yes
"limit" or "market".
tif
yes
"gtc", "ioc", "fok", or "alo".
price
yes
Human decimal string display price. For limit orders this is the limit price. For market orders this is the protection price used by execution.
quantity
yes
Human decimal string base-asset quantity.
cloid
no
0x-prefixed 16-byte client order id.
Limit order example:
Protected market order example:
cancel
Cancels one order by exchange order id or client order id. Provide oid or cloid; if both are present, oid is used.
type
yes
"cancel"
market_id
yes
Decimal string market id.
oid
conditional
Decimal string exchange order id. Required unless cloid is present.
cloid
conditional
0x-prefixed 16-byte client order id. Required unless oid is present.
cancelAll
Cancels every open resting order for the effective owner (recovered signer or agent-resolved principal) in one market. The market must exist; an unknown market is rejected by execution as MarketNotFound. A market that exists but has no open orders for this owner is a successful no-op.
Effects to confirm via reads:
The owner's
openOrdersfor thismarket_idbecomes empty.Each previously-open
oidreachesorderStatus = "cancelled"withremaining_qty = 0. Orders remain queryable by their existingoidandcloid(if any).Open orders in other markets and orders owned by other signers are unaffected.
type
yes
"cancelAll"
market_id
yes
Decimal string market id.
cancelAll carries no oid and no cloid. The missing_oid_or_cloid parse error does not apply to it. Agent signatures are accepted (same allowlist as cancel). Submit precheck classifies it (and any pure-cancelAll or cancel/cancelAll-only batch) as a pure cancel: oracle freshness, frozen SpotCreditAccount, mark coverage, quote-min-notional, and duplicate cloid checks are skipped at admission.
modify
Replaces one open order using action-atomic cancel-plus-place semantics. Provide oid or cloid; if both are present, oid is used. replacement has the same shape as an order without market_id.
type
yes
"modify"
market_id
yes
Decimal string market id.
oid
conditional
Decimal string exchange order id. Required unless cloid is present.
cloid
conditional
0x-prefixed 16-byte client order id. Required unless oid is present.
replacement.side
yes
"bid" or "ask"; "buy" and "sell" are also accepted aliases.
replacement.order_type
yes
"limit" or "market".
replacement.tif
yes
"gtc", "ioc", "fok", or "alo".
replacement.price
yes
Human decimal string display price. For limit orders this is the limit price. For market orders this is the protection price used by execution.
replacement.quantity
yes
Human decimal string base-asset quantity.
replacement.cloid
no
0x-prefixed 16-byte replacement client order id, or null to omit one.
batch
batch is the only multi-item write action. Its items array may mix these item types in payload order under one envelope nonce:
ordercancelcancelAllmodify
cancel and modify items use the same target rules as top-level actions: provide oid or cloid; if both are present, oid is used. A cancelAll item carries only market_id and behaves the same as a top-level cancelAll. A replacement has the same order shape as an order without market_id.
Batch constraints:
itemsmust contain1..=10items.Items execute in array order.
The batch has one envelope nonce. Individual items may succeed or fail inside the batch execution result.
Last updated