Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 5 min read

4 ways x402 paywalls break in production (and how to test yours)

x402 makes charging for an API call look easy: return a 402 with your price, let the client sign a USDC authorization, verify it, serve the response. The happy path works in an afternoon. The bugs live at the edges: wha

x402 makes charging for an API call look easy: return a 402 with your price, let the client sign a USDC authorization, verify it, serve the response. The happy path works in an afternoon.

The bugs live at the edges: what the client does when the network drops, what happens when ten calls arrive at once, whether your published catalog still matches the live 402, and whether the challenge says exactly what is being paid for.

Over the last weeks we reviewed several x402 sellers, buyer SDKs and agent wallets, some in code and some from the outside with unpaid requests only. These four patterns came up again and again. Names and identifying details are removed, and maintainers hear about findings privately before we write about them.

1. A retry after a lost response pays twice

The classic buyer-side failure:

  1. The client calls a paid endpoint and gets a 402.
  2. It signs a fresh authorization with a new random nonce and sends the paid request.
  3. The seller settles, but the response is lost to a timeout, a 5xx or a dropped connection.
  4. Normal retry logic starts again, gets a new 402, signs a new nonce and pays again.

A similar finding in our audit history: an SDK whose payment call supported idempotency keys, but whose auto-pay handler never passed one. It is also the mistake we planted in our own public sample audit: an agent that retries timeouts up to five times with a new payment each time.

Fix (buyer):

  • Derive an idempotency key per logical request, for example a hash of method, URL, body and the 402 challenge, and send it on every attempt.
  • On a timeout after signing, check whether the original authorization settled before you sign again.
  • Return the transaction hash on failure so the caller can resume instead of re-paying.

Fix (seller):

  • Honour an Idempotency-Key header: the same key returns the original result, not a fresh 402.
  • Return 409 if the same key arrives with a different body.

2. Spend caps that break under parallel calls

Agent wallets advertise daily caps, lifetime caps, balance floors and "never pay the same request twice". In the implementation we tested, all of those were check-then-act: read the ledger, compare, sign, and write the record only after the seller answered. Only finished payments counted.

MCP clients issue parallel tool calls, so this is not an edge case. In a local test through the real MCP server, every call in a parallel burst was paid, well past the daily cap, in every run. Parallel copies of the same idempotency key were each paid once. A per-payment cap has the same weakness from another angle: many small payments pass a limit meant for their total.

Fix:

  • Serialize the critical section from the cap check to the ledger write, in-process and across processes (a lock file works).
  • Better: write a PENDING reservation before signing, count PENDING toward caps, idempotency and the floor, and resolve it to the final status afterwards.
  • Treat a PENDING record that never resolves as unknown, not as free. That also closes the crash window.
  • Add a regression test that fires N calls with Promise.all and asserts the cap holds.

3. The catalog says one thing, the live 402 says another

Sellers publish their terms in several places: agent.json, an agent card, /.well-known/x402, OpenAPI x-payment-info, llms.txt, a quote endpoint. Buyers and directories trust those files. We compare them with live unpaid 402 challenges, field by field.

The prices usually matched. The drift was elsewhere:

  • A live 402 offered a second payment option, on another chain, to a wallet address that appeared in none of the published catalogs. The seller's own "verify before paying" rules would have rejected it.
  • An identity document that other agents are told to trust still listed two routes as free. Live, both returned 402 and charged.

Fix:

  • Generate every catalog from the same route config that builds the 402.
  • Add a CI job that fetches each catalog and diffs it against a live unpaid 402 for every paid route: amount in atomic units, asset, network, payTo, timeout, extra.
  • Retire stale identity files instead of leaving them online.

4. The 402 does not say exactly what is being paid for

Two related gaps:

  • Weak binding. On one paid route the challenge named the path only. The query string, which is the actual product on a pay-per-question endpoint, was not in resource.url. We did not test replay, but nothing in the challenge lets a careful wallet bind a payment to the specific question.
  • Split shape. One server returned a short JSON body with just a price, while the full terms (accepts, payTo, asset, atomic amount) lived only in the base64 PAYMENT-REQUIRED header. Another returned an x402 v1 body and a v2 header. Clients that read only one place cannot check the destination.

Fix:

  • Put the full request URL with a canonical query string in resource.url, or bind a hash of method, path, query and body into the requirements and verify it on settle.
  • Return the full accepts array consistently, in the shape your docs promise.
  • Say clearly in your docs that buyers must decode PAYMENT-REQUIRED.
  • Test your own client against your own server.

The checklist

Run these before you call an x402 endpoint production ready:

  • [ ] Same Idempotency-Key returns the same result with no second settlement.
  • [ ] Same key with a different body returns 409.
  • [ ] A replayed valid payment does not unlock a second request.
  • [ ] N parallel paid calls never exceed the cap.
  • [ ] A timeout after signing never leads to a second signature before settlement is checked.
  • [ ] Every published catalog matches the live 402 for every paid route.
  • [ ] resource.url names the exact request being paid for.
  • [ ] Your own client works against your own server.

Which of these would your endpoint fail today? Tell us in the comments, we read every one.

How we test

We test the live system, not only the code: unpaid requests to compare catalogs with live 402s, replayed payments on systems we are invited to test, and runnable local proofs of concept for code findings. Every finding is checked by a person before it goes out, and each one comes with a way to reproduce it.

If you want a first pass on your own app or payment flow, our architecture check is free. If you are building an agent, our MCP endpoint and its docs are here: younanix.com/llms.txt.

This article was written with the help of AI and reviewed and fact-checked by our team before publishing.

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.