Skip to main content
Every write endpoint is idempotent. Reuse the same request_id on a retry and the gateway returns the original payment or quote-request batch, with its current status, instead of creating a second one. This page is the API reference. How the key is scoped, what to do for each status, and how retries work over x402 and MPP are in the Idempotency guide.

The key: request_id

You choose the value. A stable, unique-per-operation string works best (an order id, or a UUID if you already mint them). Store it before you send the request — it’s the only thing that links a retry to its original.

Supported endpoints

Idempotency applies to state-changing (POST) endpoints. Each has its own key: reusing one across the two does not carry over. GET reads (/status, /resolve, /timeline) have no side effects, so there is nothing to deduplicate.

Detecting a replay

Every successful write response carries idempotent_replay:
  • true — you were handed a resource that already existed; nothing new was created or charged.
  • false — this request created it.

Different terms and errors

Reusing a request_id with different economics (source, destination, fulfillment_amount, max_source_amount) is refused with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature may change on a retry. Which errors let you reuse the key: When a request is refused.

Example

The request authorizes itself through its sender_auth signature — there is no API key. Re-send the exact same request, with the same request_id, to recover the original result after a timeout or crash; the response’s idempotent_replay tells you whether it was created now or already existed.
Using the SDK? You still pass requestId — the SDK derives the on-chain deposit nonce from it so both guarantees line up. The CLI generates a request_id if you omit --request-id; copy that value to retry.