Idempotency

Idempotency-Key: payout-2026-10-03-000123

Required on every POST that creates something: swaps, withdrawals, chain payouts, address registration and derivation, xpubs, deposit keys, customers and transfers. The API reference marks each one. Retire, watch-now and sweep-hold calls do not take one; repeating them changes nothing. POST /v1/quotes does not take one either: two quotes are two quotes.

Rules

Up to 120 printable ASCII characters.
One key per intent, not per attempt. Use your own record's id. A fresh random key on each attempt makes the header present and useless.
Same key, same body, first call finished: the stored answer with its original status. Nothing happens twice. On POST /v1/chain-payouts a replay carries Idempotent-Replay: true.
Same key, different body: 422 idempotency_key_reused. Nothing is done.
Same key, first call still running: 409 idempotency_key_in_progress with Retry-After. Its class is unresolved: wait, then read the resource or repeat the same key. Do not send a new key.
Keys are scoped to your tenant. Two partners may use the same string.

Code	HTTP
`idempotency_key_required`	400	The header is missing
`idempotency_key_too_long`	400	Over 120 characters
`idempotency_key_reused`	422	Same key, different body
`idempotency_key_in_progress`	409	The first call has not finished

Asking what a key produced

GET /v1/operations/by-key/{key}

For a request whose response you lost and which you must not send again. Answers:

Answer	Meaning
`ANSWERED` with an operation	The request was accepted; this is what it created
`ANSWERED` without an operation	The request was answered, for example refused, and created nothing
`IN_PROGRESS`	Claimed and not finished
`404 no_operation_for_key`	No committed record under this key

404 means no committed record, which is narrower than "it never happened": a request of yours that is still running reads the same way. Before you treat a 404 as final, make sure no request with that key is still in flight on your side.