Reliability
Retries, duplicates, timeouts and reconciliation.
Only confirmed means paid
| Status | Event | Credit or settle? |
|---|---|---|
submitted | transaction.submitted | No |
pending | transaction.pending | No |
confirmed | transaction.success | Yes |
failed | transaction.failed | No |
transaction.reconciled is the signing side's report of the same confirmation as transaction.success; act on transaction.success. transaction.summary_corrected corrects a past transaction's details and does not change its status.
Avoiding duplicate operations
| Operation | Protection |
|---|---|
| Create payment | The Idempotency-Key header is required. Reuse the same key when retrying. Unique per project. |
| Start recovery | Send an Idempotency-Key header; retries with the same key are safe. |
| Send on Bitcoin, Spark, Solana, Tron, TON | Your transactionId identifies the transfer. |
| Approvals | A signer's repeated approval is counted once. |
| Provision wallets | Wallets that already exist come back as already_exists. |
| Swaps and transfers | Never retried automatically; a second submit is refused with idempotency_conflict. |
idempotency_conflict means the key or request was already used for something different.
When a retry is refused
| Response | Meaning | Do |
|---|---|---|
409 idempotency_conflict, "retry shortly" | The first request is still running. | Wait, then retry the same request. |
409 idempotency_conflict, "needs reconciliation" | An earlier attempt may have reached the network without finishing. | Do not resend. Read List transactions first. |
Retrying by operation
| Operation | Safe to retry? |
|---|---|
| Provision wallets | Yes. Existing wallets come back as already_exists. |
| Send (EVM) | Resubmitting the same signature is counted once. Do not prepare a new payment until the first is failed. |
| Send (other networks) | Yes, with the same transactionId and details, within 24 hours. |
| Create payment | Yes, with the same Idempotency-Key. |
| Submit bridge or swap | No. Read Get bridge or List transactions instead. |
Timeouts
A timeout is not a failure; the operation may still complete. Before retrying, read its state:
| After a timeout on | Read |
|---|---|
| A payment | List transactions |
| A transfer | Get bridge |
| A swap | List transactions |
| Adding a passkey | List passkeys |
Processing notifications
- Verify
x-signature. See Setup and Verification. - Reject a notification whose
x-timestampis far from now; we recommend 5 minutes. - Skip any
x-idempotency-keyyou have already processed. - Respond
2xxquickly, then process.
Notifications can arrive out of order and more than once. Act on the status in the event, and if unsure, read the current state from the API.
Delivery guarantees are on Setup and Verification.
Reconciling
Regularly compare your records with List transactions and List wallet balances, and treat the API as the source of truth.