Idempotency
Commands that create something take an Idempotency-Key header: a UUID you generate and keep for that request. If a response is lost, send the same request again with the same key and the same body; you get the original result back and nothing happens twice. The same key with a different body is refused with 409 request_key_conflict.
| Operation | Idempotency-Key |
|---|---|
| Create a deposit, Create a deposit address, Withdraw funds, Swap tokens, Place an order | Required. For a withdrawal or a swap, use the requestKey from the quote; for an order, the one from Prepare an order. |
| Create a conversation, Start a run | Optional, but without it a retry creates a second one. |
Create a user and Create the agent wallet need no key: they return the existing user or wallet. Get a 1Click session needs none either: every call is a separate session, and one lost on its way to you simply expires unused. Report a deposit transaction records nothing, so a repeat is safe. Approving or denying is a single decision; a repeat answers 409 approval_not_pending.
After a lost money response, find what happened before trying again: list deposits or withdrawals with requestKey=<your key>. Never retry money requests automatically with a new key.