Place an order

POST/api/v1/ordersBearer

Trading APIprice E4 · size E2 · amount E6 (integers)YES | NO

202 = the command is persisted ≠ it has traded. The response body carries no matching result; take the cursor to GET /markets/{marketId}/orders/{orderId}?minCursor=… and poll.

clientOrderId (optional) is the idempotency key: supply it and retrying the same order never creates a second command (deduplicated on (trader, clientOrderId); a replay returns the original response). Omit it and a retry may place a duplicate order — that risk stays with you. clientOrderId and the orderId in the response are two different domains and must not be mixed — orderId is always generated server-side.

With auth (an on-chain order signature) a byte-level admission check runs; on failure you get a 400 and the command is not logged and no funds are frozen, so fix the assembly and resend — retrying is pointless. On a 503 the error is one of command_log_unavailable / seq_unavailable / duplicate_in_flight (all safe to retry).

`tif: FOK` and `auth` cannot be combined. The off-chain engine supports FOK fully (fill in full or reject the whole order), but the on-chain settlement contract treats FOK's order_type as a reserved value and aborts outright (unsupported_order_type). This layer will not stop you: a signed FOK order is accepted normally, returns 202 and freezes funds, then stalls at settlement. Use GTC or GTD for signed orders.

Send Authorization: Bearer <token>. The token is issued by POST /api/v1/auth/verify, and expires after 24h idle or 7d after issuance.

Request body

marketIdstringrequired
Engine market id
Example"mkt-0001"
clientOrderIdstringoptional
Caller-chosen idempotency key; without it, a retry may place a duplicate order
Example"mm-btc-2026-09-19-0001"
outcomeYES | NOrequired
Settlement outcome
Example"YES"
sideBUY | SELLrequired
Order side
Example"BUY"
priceE4integerrequired
1e-4 USD; must be a multiple of the market's tickE4
Range1 – 9999Example5200
sizeE2int64required
1e-2 shares
Range≥ 1Example1000
tifGTC | GTD | FAK | FOKoptional
Omitting it is the same as GTC. GTD must also supply expiration. FAK fills what it can immediately and cancels the rest; FOK fills in full or the whole order is rejected (with the reason FOK 无法全量成交). `FOK` is only usable on off-chain orders that carry no `auth` — with an on-chain signature it is guaranteed to fail at settlement, see this endpoint's description
Default"GTC"Example"GTC"
expirationint64optional
Unix seconds; required for GTD, and required for a signed order carrying auth
Example1758243600
postOnlybooleanoptional
true = post only; the whole order is rejected if it would trade immediately. Omitting the field is the same as false
DefaultfalseExamplefalse
authobjectoptional
On-chain order signature payload; omit it to take the unsigned path, which markets in on-chain mode reject
orderBytesstringrequired
OrderV1 bytes (hex; market_id must be the on-chain Market object id)
signaturestringrequired
Order signature (hex)
accountEpochintegeroptional
Read from the chain by the client (TradingAccount.order_epoch); the backend does not proxy it
Example0

Response

202Command persisted (not matched)

orderIdstring
Server-generated order id, used for subsequent status queries and cancellation
Example"ord_01K5H2M3N7Q8R9S0"
clientOrderIdstringnullable
The idempotency key from the request, echoed verbatim; null when it was omitted
Example"mm-btc-2026-09-19-0001"
cursorstring
Read-your-writes continuation point; pass it verbatim as the minCursor of the status query
Example"c1:mkt-0001:184"
commandIdstring
Command identifier
Example"cmd_01K5H2M3N7Q8R9S1"

Switch status codes in the response example to view errors. For all codes, see the Errors page.

Request

curl -X POST "$BASE_URL/api/v1/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "mkt-0001",
    "outcome": "YES",
    "side": "BUY",
    "priceE4": 5200,
    "sizeE2": 1000,
    "tif": "GTC",
    "postOnly": false
  }'

Response

Command persisted (not matched)

{
  "orderId": "ord_01K5H2M3N7Q8R9S0",
  "clientOrderId": "mm-btc-2026-09-19-0001",
  "cursor": "c1:mkt-0001:184",
  "commandId": "cmd_01K5H2M3N7Q8R9S1"
}

Place an order

POST/api/v1/ordersBearer

Trading APIprice E4 · size E2 · amount E6 (integers)YES | NO

202 = the command is persisted ≠ it has traded. The response body carries no matching result; take the cursor to GET /markets/{marketId}/orders/{orderId}?minCursor=… and poll.

Send Authorization: Bearer <token>. The token is issued by POST /api/v1/auth/verify, and expires after 24h idle or 7d after issuance.

Request body

marketIdstringrequired

Engine market id

Example"mkt-0001"

clientOrderIdstringoptional

Caller-chosen idempotency key; without it, a retry may place a duplicate order

Example"mm-btc-2026-09-19-0001"

outcomeYES | NOrequired

Settlement outcome

Example"YES"

sideBUY | SELLrequired

Order side

Example"BUY"

priceE4integerrequired

1e-4 USD; must be a multiple of the market's tickE4

Range1 – 9999Example5200

sizeE2int64required

1e-2 shares

Range≥ 1Example1000

tifGTC | GTD | FAK | FOKoptional

Omitting it is the same as GTC. GTD must also supply expiration. FAK fills what it can immediately and cancels the rest; FOK fills in full or the whole order is rejected (with the reason FOK 无法全量成交). `FOK` is only usable on off-chain orders that carry no `auth` — with an on-chain signature it is guaranteed to fail at settlement, see this endpoint's description

Default"GTC"Example"GTC"

expirationint64optional

Unix seconds; required for GTD, and required for a signed order carrying auth

Example1758243600

postOnlybooleanoptional

true = post only; the whole order is rejected if it would trade immediately. Omitting the field is the same as false

DefaultfalseExamplefalse

authobjectoptional

On-chain order signature payload; omit it to take the unsigned path, which markets in on-chain mode reject

orderBytesstringrequired

OrderV1 bytes (hex; market_id must be the on-chain Market object id)

signaturestringrequired

Order signature (hex)

accountEpochintegeroptional

Read from the chain by the client (TradingAccount.order_epoch); the backend does not proxy it

Example0