x402 Facilitator Security Checklist

By the Guardian team Updated November 2026 6 min read

Quick answer. Claim each payment atomically in a store every /settle instance shares, and check the onchain nonce before broadcasting. Report success only on a confirmed transfer of the exact amount to payTo, keeping keys until the payment cannot land.

Watch: x402 Facilitator Security Checklist 1:44

Video transcript

With x402, verify and settle are separate calls. In that gap, one payment can get a resource delivered twice.

Wang et al. tested 15 facilitators against eight security rules. Every one broke at least one.

Verify does not reserve the nonce. As the x402 spec puts it, the chain stops double-spend, not double-delivery.

Ling et al. sent concurrent requests to Coinbase's CDP facilitator on Base mainnet. Six percent of rounds produced duplicate delivery, with one settlement onchain.

Close the gap with an atomic claim in a store every settle instance shares. Re-verify inside settle, check the nonce onchain, and reject any second claim.

Key dedupe on the payer and nonce, and hold each key until the payment can no longer land. Require the exact amount and payTo, and bind each payment to one resource, since the signature does not cover it.

A receipt only proves the transaction did not revert. Report success on the expected Transfer of the exact amount. If the receipt is missing, return settlement pending with the hash.

The facilitator also pays the gas. Wang et al. counted 5.8 thousand dollars in gas and fees from reverting settlements alone. Cap gas, and size verify limits to settlement capacity.

Guardian's API pentest covers replay protection, rate limiting and out of order flows. Read the full checklist, including monitoring, or talk to Guardian at guardian.security.

With x402, an AI agent pays for an API call with a signed stablecoin authorization. The facilitator is the service that checks the signature and puts the payment onchain.

Its weak point sits between those two jobs. Verify and settle are separate calls, and one payment can unlock a resource twice in the gap.

Three academic papers from May to July 2026 studied these flaws. In one, Wang et al. tested 15 facilitators: every one broke at least one of their eight security rules.

The Facilitator Role

x402 has three parties: a client, a resource server and a facilitator. The spec defines the facilitator as "a service that handles payment verification and blockchain settlement".

It has three endpoints:

POST /verify checks a payment against the server's requirements. It must not commit payment state or write onchain.
POST /settle commits the payment, typically by broadcasting a transaction.
GET /supported lists its schemes, networks and public signer addresses.

On EVM chains the default method is EIP-3009. The payer signs a transfer authorization, and the facilitator submits it and pays the gas.

The x402 docs say the facilitator "does not hold funds or act as a custodian". The EVM scheme adds that it "cannot modify the amount or destination".

Where trust sits

Control	Enforced by	Still your problem
Amount and recipient	The payer's EIP-712 signature	Matching them to the server's requirements
Single settlement	The token contract's nonce	Delivering twice before the nonce is spent
Lifetime	validAfter and validBefore	Windows long enough to leak and reuse
Success report	The facilitator	Reporting success for a payment that never landed
Gas	The facilitator's wallet	Attackers steering it into costly failures

The public x402.org facilitator is for testnets. In production, use a hosted one, such as Coinbase's CDP facilitator with OFAC and KYT screening, or your own.

Verify vs Settle Atomicity

The default flow runs verify, then the resource, then settle, then the response. Nothing in that sequence is atomic.

Verify is read-only by design. As Wang et al. put it, "/verify is stateless and does not reserve the payment nonce", so two requests with the same payload can both pass.

The x402 exact scheme names the result: "the network primitive prevents double-spend, not double-delivery".

Ling et al. measured it on Coinbase's CDP facilitator on Base mainnet. Fifty rounds of 20 concurrent requests "produced duplicate service delivery in 6% of rounds", with one settlement onchain.

The fixes:

Claim the payment atomically before settling, with a check-and-set such as a distributed lock.
Re-run full verification inside /settle.
Reject a second claim with a clear error, never a silent retry.
For handlers that outlast the validity window, use upfront. It settles first, and the spec defines no refund.

Replay and Idempotency

Nonces, validity windows and signatures stop a payment settling twice. They do not stop it being counted twice, or spent on a different resource.

The dedupe key

Key on what the chain treats as single-use: for EIP-3009, the payer and nonce on that token.
On Solana, key on the signed transaction. A resubmission there looks identical to the original.
Store keys where every instance sees them. For such methods, the spec requires dedupe "across every process serving /settle".
Keep each key until the payment can no longer land: past validBefore, or blockhash expiry on Solana.

The reference Solana cache is an in-memory map that evicts after 120 seconds. One process can see it; a fleet behind a load balancer cannot.

Amount, recipient and resource

Require the authorization's recipient to equal payTo and its value to equal the amount exactly.
Check authorizationState onchain before broadcasting, so a spent nonce fails early.
Bind each payment to one resource on your side, and claim the pair atomically.

The signature does not cover the resource. Li, Wang and Wang examined three open-source SDKs and found that "no audited SDK binds a payment to the intended resource".

Leaked headers are a second risk. Anyone holding one can submit transferWithAuthorization first, for "a preempting L2 transaction fee, typically at the cent level".

The money still reaches payTo, but the honest settle fails and the client is refused. EIP-3009's receiveWithAuthorization blocks this by checking the caller is the payee, but x402 uses transferWithAuthorization.

Keep payment headers out of logs, proxies and analytics.

Finality

Report success only once the payment settles onchain. Wang et al. name the failure: "returning true while the settlement transaction reverts, is dropped, or is never confirmed on chain".

A receipt is not enough. The reference EVM code notes that receipt status "only proves the tx did not revert", so it also requires the expected Transfer event.

If the receipt cannot be fetched, return the non-terminal settlement_pending code with the broadcast hash, so the caller can reconcile before retrying.

Finality on Base comes in stages.

Stage	Typical time	Base's reorg note
Flashblock inclusion	About 200 ms	Targets a reorg rate below 0.1%
L2 block inclusion	About 2 s	Only one L2 block has ever reorged
L1 batch inclusion	About 2 min	No batched L2 block has ever reorged
L1 batch finality	About 20 min	"In practice impossible to reverse"

A server that grants on an early signal can lose the payment to a delay, replacement or reorg. Li, Wang and Wang suggest higher-value resources wait for confirmations.

Set a finality stage per price tier, and reconcile every pending hash before releasing its dedupe key.

Rate Limits and Gas

Verification is cheap; settlement is not. Mismatched limits are an attack surface.

Ling et al. tested a third-party deployment: "a 50-req/s burst against the default 10-tx/s settlement limit streamed all 50 requests (100%) but settled only 5 (10%)".

The facilitator also pays the gas. Across Base and Solana, Wang et al. counted $5.8K in gas and fees from reverting x402 settlement submissions alone.

Size verify limits to settlement capacity, and return 429 before serving when settlement is full.
Rate limit per payer, per resource server and per API key.
Cap gas, priority fees and Solana compute units, and reject dust payments.
Allowlist smart wallet factories. Wang et al. found an ERC-6492 asset theft bug in a top-volume facilitator.

Monitoring

Most failures show up as a gap between what you served and what settled. Watch:

Paid responses against confirmed settlements, per resource server.
Pending settlements older than their validity window.
Reverts, and gas per successful settlement.
Nonce-already-used failures and duplicate-claim rejections, by payer.
Any transaction from your signer addresses that is not a settlement.
Advisories for every x402 package you run.

In March 2026, a high-severity advisory told facilitators processing Solana payments to upgrade: @x402/svm 2.6.0, Python x402 2.3.0 and Go 2.5.0 or later.

For the detection side, see what onchain monitoring covers.

How Guardian Helps

A facilitator is an API that fires onchain transactions. Guardian's API pentest covers rate limiting, replay protection and "multi-step flows that can be interrupted, replayed, or driven out of order".

The offchain automation pentest covers relayers and bots that hold privileges, and "what a mistimed, skipped, or duplicated run does onchain".

After launch, Managed Security runs Helix across contracts, backend services and infrastructure, with 24/7 monitoring and response. It matches new disclosures against what you run.

x402 also runs over MCP: see our MCP pentesting checklist. For banks and fintechs, read agentic payments security.

Frequently Asked Questions

What does an x402 facilitator do?

It verifies a client's signed payment against the server's requirements, then settles it onchain and usually pays the gas. It holds no funds and, on EVM chains, cannot change the amount or recipient.

Does the EIP-3009 nonce prevent double settlement?

It stops one authorization settling twice onchain. It does not stop two requests passing /verify, or a server delivering twice before the nonce is spent. That needs an atomic claim before settlement.

Should I run my own x402 facilitator?

You can: the x402 docs list self-hosting as the option with full operational control. You then own the signer key, gas, dedupe store and finality policy.

When should a facilitator report settlement success?

Only after the transfer is confirmed onchain, with the expected Transfer of the exact amount to payTo. If the receipt is missing, return settlement_pending with the hash and reconcile first.

Sources

Pentest your facilitator before attackers do

Guardian pentests the verify and settle path for replay, rate limit gaps and out-of-order flows, then keeps it under continuous testing and monitoring.

Talk to Guardian Explore Managed Security