Client order id

clientOrderId is an optional tag you attach to an order on POST /orders-v3. It is your own value, echoed back to you on the create response, the order row, the orders channel, and in the fills grain. clientOrderId has no effect on funds, fees, or matching.

Why it is useful

You do not know an order’s id until POST /orders-v3 responds. That makes correlation awkward when the pieces of one order’s story arrive on different paths: the HTTP response, and then separate publications on account:orders_v3_#{address}. A clientOrderId is a value you choose before you submit, so you can stitch those messages together against your own records the moment each one lands, rather than waiting on the id. This is the standard pattern on async trading platforms: attach your own reference at submit time, then match it back as updates flow in.

Format

Rule	Value
Optional	Omit it and the field is absent from responses
Max length	64 characters
Allowed characters	`^[A-Za-z0-9_-]+$` — letters, digits, `_`, `-`

Uniqueness

A clientOrderId must be unique per address — not just within one request, but across every order you currently have in the system. The safe rule is to treat each clientOrderId as single-use. Generate a fresh value per order — for example strategy-<nonce> — and never reuse one, exactly as you would mint a fresh salt per order.

Where it shows up

clientOrderId is echoed on the order grain:

POST /orders-v3 — the 201 body’s orders array echoes your clientOrderId on each result when you set one, alongside orderId, status, and commandId.
GET /orders-v3 — each order row carries clientOrderId when set.
account:orders_v3_#{address} — each publication carries it too when set.

It is also echoed on the fill grain, so you can trace a fill straight back to the order that produced it:

GET /fills-v3 and account:fills_v3_#{address} — each fill carries the clientOrderId of the order on that side (the maker’s tag on maker rows, the taker’s on taker rows) when that order carried a tag; otherwise the field is omitted.

Recommended pattern

JavaScript

// Mint a fresh, single-use id and record what you need before you submit.
const clientOrderId = `mm-${crypto.randomUUID()}`;

myOrders.set(clientOrderId, {
  timeInForce: "GTC",       // write-only on the API — record it yourself
  marketHash,
  submittedAt: Date.now(),
});

await fetch(`${API}/orders-v3`, authed({
  method: "POST",
  body: JSON.stringify({ orders: [{ ...order, clientOrderId }] }),
}));

// Later, on account:orders_v3_#{address}, look each update up by its clientOrderId.

Because timeInForce is write-only, recording it against your clientOrderId at submit time is the reliable way to know later which type an order used.

Posting orders

The submit flow this field rides on.

Time in force

The other write-only field worth recording against your tag.

Tracking your orders

Keep a local store keyed by an id you control.

EIP-712 order signing

Why the order id is a digest, not a server-assigned value.

External user id

A per-person tag when one SX account places orders for many people.

Getting Started

Upgrading to V3

Accounts & Funding

Core Concepts

Markets

Market Data

Realtime Data

Trading

Lifecycles

My Activity

Partners

Resources

Why it is useful

Format

Uniqueness

Where it shows up

Recommended pattern

Posting orders

Time in force

Tracking your orders

EIP-712 order signing

External user id

​Why it is useful

​Format

​Uniqueness

​Where it shows up

​Recommended pattern

​Related

Posting orders

Time in force

Tracking your orders

EIP-712 order signing

External user id

Why it is useful

Format

Uniqueness

Where it shows up

Recommended pattern

Related