Idempotency & client order id
Orbitum keys order idempotency on your clientOrderId in the request body —
there is no Idempotency-Key header. (Unlike Stripe/Fireblocks/Circle, which
use a header or a separate body key.)
Uniqueness scope
An order is deduplicated on the tuple (partner, exchangeUserId, clientOrderId).
Choose a clientOrderId that is unique per end user for each distinct order.
Replay semantics
| You send | Result |
|---|---|
Same clientOrderId, same parameters | Replay — the original order is returned; no second order is created. Safe to retry after a network error. |
Same clientOrderId, different parameters | Conflict — CEX_IDEMPOTENCY_CONFLICT (422). The original order is unchanged. |
Safe retry
# Network error on the first attempt? Re-send the identical request with the
# same clientOrderId — you get the original order back, not a duplicate.
curl https://api.orbitum.io/api/v1/cex/orders \
-H "X-Api-Key: $ORBITUM_API_KEY" -H "Content-Type: application/json" \
-d '{"exchangeUserId":"user-123","clientOrderId":"ord-2026-0001","product":"ORBIS","usdtAmount":"10000.00"}'
Reusing an id with changed fields (e.g. a different usdtAmount) is treated as a
mistake, not a new order — fix the id or the params.