Skip to main content
Send Idempotency-Key on every order create, cancel, and replace request.
Generate the key in your backend as a UUID; any other format is rejected with 400. If idempotency_key also appears in the JSON body, it must match the header. If you send neither, the server generates a key for you and the request cannot be retried safely.

​
How Order Idempotency Works

The key protects against a duplicate command reaching the exchange. It does not replay the original response.
  • The first request with a key is processed and answered with a fresh order_id.
  • A retry with the same key within a limited window is also answered 200 with a fresh order_id, but its command is discarded as a duplicate. That second order_id never becomes a real order.
  • A request with the same key but a different body is not rejected. Inside the window it is discarded like any duplicate; after the window it is a new order.
  • After the window has passed, the same key creates a second order.
Because of this, treat the order_id from a retry as untrusted and reconcile from client_order_id, which is unique within your account, or from an order list filtered to the pair and status you expect.

​
What Counts As The Same Intent

Use one idempotency key for one business action: If you change the order quantity, price, side, or pair, generate a new key. If you are only retrying because the network failed or the response was uncertain, reuse the original key.

​
Storage Pattern

Store the idempotency key before sending the API request.
When the first attempt returns an order_id, attach it to the local action. If the request times out before a response, retry with the same key, then find the live order by client_order_id and attach that order_id instead of the one the retry returned.

​
Response Handling

​
Checklist

  • Store the key and a unique client_order_id with your local order action before sending the request.
  • Retry uncertain responses with the same key, then reconcile by client_order_id.
  • Generate a new key only for a new intent.
  • Do not expect a 409; order writes never return one.
  • Always use a UUID; other formats are rejected.
  • Keep idempotency keys out of logs if your logs are widely accessible.