> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intention.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Client order ID
> Attach your own identifier to an order so you can cancel and reconcile by a value you chose, rather than one the chain assigns.
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.
```
0xa1b2c3d4e5f6789012345678901234ab
```
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
| Operation | Behavior |
| ------------------------------ | -------------------------------------------------------------------------------------- |
| **Cancel by client order ID** | Cancels the live order carrying that identifier, without needing the chain-assigned ID |
| **Look up by client order ID** | Retrieves the order's current state and history |
| **Reconcile** | Match your own records against chain records by an identifier you assigned |
## 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
Changing a live order, and what happens to its identifiers.
What you can attach an identifier to.
Submitting orders and handling ambiguous responses in code.
Why a cancel submitted in the same block runs before an aggressive order.