Preventing replay and duplicate charges in x402 requires more than checking a signature: bind the payment to the requested terms, enforce the selected scheme’s single-use mechanism, and coordinate atomic deduplication across every server and settlement worker. Also choose deliberately whether payment commits before or after the protected resource runs. Those choices are scheme- and network-specific; there is no universal replay key or retry contract.
Understand what can be replayed
An x402 request commonly begins with a client requesting a resource and receiving 402 Payment Required. The client selects a payment requirement, creates a payment payload, and resubmits with the payment header. The resource server or a facilitator verifies the payment, the resource is processed, settlement occurs, and the server returns the resource and settlement response. The exact ordering varies by scheme, transfer method, and network.
Two different failures matter. A replay can make the same payment proof appear valid for another request, or a duplicate submission can cause the protected handler to run or return success more than once. Preventing a second token transfer does not necessarily prevent a second API call from appearing successful. Conversely, rejecting a duplicate payment does not necessarily recover a resource response lost in transit.
Choose the payment order deliberately
The x402 v2 specification describes three payment orderings. Select the one that matches the scheme and the failure trade-offs of your handler; do not assume that every x402 flow verifies, executes, and then settles.
#1 Best Overall
- POWERFUL SECURITY KEY: The Security Key C NFC is the essential physical passkey for protecting your digital life from phishing attacks. It ensures only you can access your accounts.
- WORKS WITH 1000+ ACCOUNTS: Compatible with Google, Microsoft, and Apple. A single Security Key C NFC secures 100 of your favorite accounts, including email, password managers, and more.
- FAST & CONVENIENT LOGIN: Plug in your Security Key C NFC via USB-C and tap it, or tap it against your phone (NFC) to authenticate. No batteries, no internet connection, and no extra fees required.
- TRUSTED PASSKEY TECHNOLOGY: Uses the latest passkey standards (FIDO2/WebAuthn & FIDO U2F) but does not support One-Time Passwords. For complex needs, check out the YubiKey 5 Series.
- BUILT TO LAST: Made from tough, waterproof, and crush-resistant materials. Manufactured in Sweden and programmed in the USA with the highest security standards.
| Ordering | Sequence | Key consequence |
|---|---|---|
authorization |
Verify → resource → settle → respond | Verification is read-only; funds move only after successful resource execution. |
upfront |
Settle → resource → respond | Payment commits before the handler. The client may be charged even if the handler fails. |
escrow |
Settle → resource → settle → respond | An initial settlement commits a deposit or ceiling; a later settlement records the final charge. |
The v2 invariant is that a verify or settle check must happen before resource execution. The exact scheme defaults to authorization and recommends it where the transfer method permits it. Upfront settlement can be useful if handler duration could outlast a validity or replay bound. In escrow, distinguish the settlement steps: a generic deduplication key that treats both settles as identical could suppress a legitimate second step.
Bind the payment to the request
A proof that payment occurred is not necessarily proof that it paid for this resource. If a proof is not bound to the requested terms, it may be presented against another resource server that shares the same payee. Use the binding mechanism defined by the selected scheme—for example, a unique instrument, a server-issued nonce, a payer signature over the requirements, or a payee commitment embedded in the instrument.
Validate that binding and the scheme’s requirements before the protected handler runs. Do not treat a valid signature alone as evidence that a payment is unused: the same signed authorization or proof may be presented again unless its replay primitive and validity rules are enforced.
Rank #2
- POWERFUL SECURITY KEY: The YubiKey 5C NFC is the most versatile physical passkey, protecting your digital life from phishing attacks. It ensures only you can access your accounts
- WORKS WITH 1000+ ACCOUNTS: Compatible with popular accounts like Google, Microsoft, and Apple. A single YubiKey 5C NFC secures 100+ of your favorite accounts, including email, password managers, and more
- FAST & CONVENIENT LOGIN: Plug in your YubiKey 5C NFC via USB and tap it, or tap it against your phone (NFC), to authenticate. No batteries, no internet connection, and no extra fees required
- MOST SECURE PASSKEY: Supports FIDO2/WebAuthn, FIDO U2F, Yubico OTP, OATH-TOTP/HOTP, Smart card (PIV), and OpenPGP. That means it’s versatile, working almost anywhere you need it
- PRIMARY & SPARE KEYS: Just like having a spare house key, we recommend buying two YubiKeys - one for daily use and one as a spare. That way you’ll never get locked out of your accounts
Enforce single use and claim proofs atomically
Use the network’s replay primitive
Use the actual single-use mechanism for the transfer method and network, and verify its scope and concurrency behavior against your application’s needs. For example, the x402 v1 specification’s EIP-3009 flow describes a payer-signed authorization with a 32-byte random nonce, a validity window, and contract-level nonce-reuse prevention. That is an example, not a universal x402 replay key.
For the v2 exact scheme, a consumed replay primitive must cause settlement failure. Confirm that your integration rejects a consumed authorization rather than reporting success.
Make proof consumption a single atomic claim
For client-submitted proofs, the v2 exact scheme requires concurrent presentations of the same payment to produce at most one successful claim. Its canonical consumption key combines the CAIP-2 network identifier with that network’s canonical payment identifier. Retain the consumed proof for as long as it remains presentable.
Rank #3
- POWERFUL SECURITY KEY: The YubiKey 5 NFC is the most versatile physical passkey, protecting your digital life from phishing attacks. It ensures only you can access your accounts
- WORKS WITH 1000+ ACCOUNTS: Compatible with popular accounts like Google, Microsoft, and Apple. A single YubiKey 5 NFC secures 100+ of your favorite accounts, including email, password managers, and more
- FAST & CONVENIENT LOGIN: Plug in your YubiKey 5 NFC via USB and tap it, or tap it against your phone (NFC), to authenticate. No batteries, no internet connection, and no extra fees required
- MOST SECURE PASSKEY: Supports FIDO2/WebAuthn, FIDO U2F, Yubico OTP, OATH-TOTP/HOTP, Smart card (PIV), and OpenPGP. That means it’s versatile, working almost anywhere you need it
- PRIMARY & SPARE KEYS: Just like having a spare house key, we recommend buying two YubiKeys - one for daily use and one as a spare. That way you’ll never get locked out of your accounts
The claim must be atomic and visible to all workers that can handle the request. A check-then-write sequence in separate operations can let simultaneous requests both observe an unused proof and both proceed. Claim first; only the worker that wins the claim may continue to the handler.
Deduplicate settlement across workers
Network-level double-spend protection can prevent duplicate token movement while two API calls still appear successful. When a resubmission cannot be distinguished from the original settlement, the v2 exact scheme requires atomic deduplication across every process serving /settle. Keep the deduplication key until that payment can no longer land.
Recommended Free Tools
For schemes with multiple settlement steps, include enough scheme-specific step identity to tell a legitimate later settle from a retry of an earlier one. Derive the canonical payment identity and step identity from the scheme; do not assume one generic idempotency key works for every flow.
Rank #4
- POWERFUL SECURITY KEY: The Security Key NFC is the essential physical passkey for protecting your digital life from phishing attacks. It ensures only you can access your accounts.
- WORKS WITH 1000+ ACCOUNTS: Compatible with Google, Microsoft, and Apple. A single Security Key NFC secures 100 of your favorite accounts, including email, password managers, and more.
- FAST & CONVENIENT LOGIN: Plug in your Security Key NFC via USB-A and tap it, or tap it against your phone (NFC) to authenticate. No batteries, no internet connection, and no extra fees required.
- TRUSTED PASSKEY TECHNOLOGY: Uses the latest passkey standards (FIDO2/WebAuthn & FIDO U2F) but does not support One-Time Passwords. For complex needs, check out the YubiKey 5 Series.
- BUILT TO LAST: Made from tough, waterproof, and crush-resistant materials. Manufactured in Sweden and programmed in the USA with the highest security standards.
Handle the SVM exact settlement race
The exact-SVM guidance describes a race in which the same transaction is sent to /settle more than once before on-chain confirmation. Each caller can receive success even though Solana executes the transfer once, potentially allowing one payment to unlock more than one resource.
The scheme guidance recommends a short-lived in-flight cache keyed by the transaction payload and rejecting duplicate submissions with duplicate_settlement. It gives 120 seconds as an eviction example tied to its stated approximate blockhash lifetime. Treat that duration as SVM-specific guidance, not a universal x402 retention period; use the validity and landing behavior of the actual network and transfer method.
Keep duplicate rejection separate from response recovery
A payment can settle successfully while the HTTP response is lost. If the client retries, payment deduplication may correctly reject another settlement but still leave the client without the original resource body. Design response recovery separately from charge prevention.
Best Value
- POWERFUL SECURITY KEY: The YubiKey 5 is a versatile physical passkey that protects your digital life from phishing attacks. It ensures only you can access your accounts.
- WORKS WITH 1000+ ACCOUNTS: Compatible with popular accounts like Google, Microsoft, and Apple. A single YubiKey 5 secures 100+ of your favorite accounts, including email, password managers, and more.
- FAST & CONVENIENT LOGIN: Plug in your YubiKey 5 via USB and tap it to authenticate. No batteries, no internet connection, and no extra fees required.
- MOST SECURE PASSKEY: Supports FIDO2/WebAuthn, FIDO U2F, Yubico OTP, OATH-TOTP/HOTP, Smart card (PIV), and OpenPGP. That means it’s versatile, working almost anywhere you need it.
- BUILT TO LAST: Made from tough, waterproof, and crush-resistant materials. Manufactured in Sweden and programmed in the USA with the highest security standards.
The SVM batch-settlement behavior specifies that reusing a running or completed (channelId, requestId) returns duplicate_settlement, does not run the handler again, and does not replay the response or resource body. A transport retry requires a new request ID; the documented payment identifier extension is the option for response recovery. Do not infer that a duplicate-settlement response automatically means the original body can be fetched again.
The v2 specification distinguishes read-only /verify from state-committing /settle. A scheme may settle more than once in escrow and must define how the facilitator distinguishes those steps. The available specifications do not establish one universal idempotency-key response contract for all schemes, so define and test your API’s behavior for repeated verify and settle requests rather than assuming retries are interchangeable.
Implementation checklist
- Identify the exact scheme, network, and transfer method. Read their current requirements for payment order, canonical payment identifier, replay primitive, validity window, and settlement behavior.
- Validate the payment against the advertised requirements. Check request binding and the scheme’s verification or settlement conditions before invoking the resource handler.
- Atomically claim the payment identity. Make the claim visible across all resource-server and facilitator workers, and prevent a losing concurrent request from running the handler.
- Deduplicate settlement with step-aware identity. Coordinate state across every
/settleprocess; distinguish a legitimate second escrow settle from a retry of the first. - Set retention from the payment’s actual replay horizon. Keep consumed-proof and settlement-deduplication state until the proof cannot be presented or the payment can no longer land, as applicable to the mechanism.
- Specify retry and recovery outcomes separately. Define what the client receives for a duplicate, what happens if the handler fails after an upfront commit, and whether a lost response can be retrieved without re-executing the handler.
What to compare when choosing a mechanism
Before deploying a flow, compare these properties for the chosen scheme and network. They determine both the duplicate-charge risk and what a client can expect after a failed or interrupted request.
- When funds commit relative to resource execution.
- Whether the client or facilitator submits the transfer.
- Which replay primitive applies and whether it is exclusive to a payment or shared with payer account state.
- The proof or authorization validity window and the safe retention horizon for consumed state.
- Whether duplicate network submissions can be distinguished from legitimate later settlement steps.
- Whether deduplication state is shared across all settlement workers.
- Whether lost-response recovery is supported independently of duplicate rejection.
Version and scope
The flow descriptions above reflect the x402 v2 specification and scheme guidance, with the v1 specification used for its explicit EIP-3009 replay details. The project’s v2 materials make clear that ordering and mechanics vary by scheme, transfer method, and network. Specifications on a moving branch can change, so implement against the precise version and scheme/network combination your deployment uses.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
