x402-server-guard

Wrap your x402 payment endpoint to close the settlement race, replay, cross-resource substitution, grant-before-finality, and cache-leakage holes. Vulnerable code first, fixed code second, on every page.

Read the guideGitHub

This is the teaching companion to the library. It explains, without assuming you know crypto, what each attack is, how it lets someone cheat a paid endpoint, and how the guard stops it. The authoritative, code-exact facts live in the repository: coverage map ties each attack to the test that proves it, and hardening explains the mechanisms in depth. These guides are the friendly narrative; when in doubt, the repo is the source of truth.

New to x402? Start with Understanding x402, a short attack-relevant primer (the 402 flow, the signed payment, the nonce, and the verify vs settle gap). Everything else assumes it.

The attacks and the fixes

Race & replayFire the same payment many times at once and get many resources for one payment. Fix: reserve the nonce before delivering.

Cross-resource substitutionSpend a payment meant for resource A at resource B. Fix: bind the nonce to the served resource.

Grant-before-finalityGet the resource, then have the payment reversed by a chain reorg. Fix: hold to k confirmations, release on failure.

Cache leakageA shared cache serves the paid response to unpaid clients. Fix: no-store, private on paid responses.

The research

The attacks come from two papers. Each page cites the specific attack or invariant it addresses.

• Zelin Li, Qin Wang, Zhipeng Wang. “Five Attacks on x402 Agentic Payment Protocol.” https://arxiv.org/abs/2605.11781
• Shengchen Ling et al. “Free-Riding the Agentic Web: A Systematic Security Analysis of x402 Payments.” https://arxiv.org/abs/2605.30998

One honest disclaimer

This library is not audited and is not a security guarantee. It mitigates these specific attack classes. It cannot make an insecure endpoint safe on its own.