Skip to main content
When you submit an order, the chain assigns it an order ID. That ID is authoritative, but you only learn it after the order is accepted — which is a problem if the thing you need to do is cancel an order whose acceptance you never saw. A client order ID solves that. You generate the identifier yourself, attach it at submission, and can act on the order by that identifier from the moment you send it.

​
Why this matters more than it sounds

Consider a submission that times out. Did it reach the chain? You do not know. Without a client order ID your options are to query recent orders and guess by market, side, price, and quantity, or to do nothing and hope. With one, the ambiguity disappears. You cancel by the identifier you generated. If the order existed, it is cancelled. If it never arrived, the cancel finds nothing. Either way you end in a known state, which is what a system running without a human watching actually needs. This is also what makes reconciliation tractable. Your own records key on an identifier you assigned, so matching your view against the chain’s is a lookup rather than a heuristic.

​
Format

The identifier is a 16-byte value, submitted as a 0x-prefixed, lowercase hexadecimal string of 32 characters.
Three rules the protocol enforces:
  • Lowercase only. Uppercase hex is rejected rather than normalized.
  • Exact length. Shorter or longer values are rejected.
  • All-zero is reserved. 0x00000000...0000 is the sentinel meaning absent and cannot be used as an identifier.
The field is optional. An order without one behaves normally in every respect — it simply cannot be cancelled by client order ID, only by the chain-assigned order ID.

​
Uniqueness

Uniqueness is scoped to the sub-account: the combination of the signing address and the sub-account under it. Two consequences follow. Different sub-accounts under the same address may use the same identifier without conflict — useful when running independent strategies that each generate their own IDs. And within one sub-account, reusing an identifier that belongs to a live order is an error rather than a replacement.
Generate identifiers randomly rather than sequentially. A counter is tempting because it makes ordering visible, but a restart that loses the counter produces collisions with orders that are still live, and 16 random bytes never collide in practice.

​
What you can do with it

​
Lifetime

The identifier belongs to the order, not to your session. It stays queryable after the order is filled or cancelled, which is what makes it useful for reconciliation after the fact. It becomes reusable once the order it identified is no longer live. In practice there is little reason to reuse one — a fresh random value costs nothing and removes any question about which order a historical record refers to.

​
Where to go next

Modify orders

Changing a live order, and what happens to its identifiers.

Order types

What you can attach an identifier to.

Developers

Submitting orders and handling ambiguous responses in code.

Transaction sequencing

Why a cancel submitted in the same block runs before an aggressive order.