We run a set of paid x402 endpoints on Base. Most of the hours we lost were not in our code logic. They were in the 402 answer itself: one wrong field, and every payment fails with an error that points somewhere else.

This week we wrote a small checker for those mistakes and ran it, read-only, against 40 live endpoints from the Coinbase x402 discovery list, one per host. All 40 passed the hard checks. That makes sense: an endpoint only gets listed after a payment has settled once. So the traps below hit you before launch, while you build, which is where a checker earns its keep.

Trap 1: the EIP-712 domain in extra

For the exact scheme on EVM, the client signs a USDC transferWithAuthorization. The domain name and version come from accepts[].extra. If they do not match what the token contract uses, every signature fails verify.

We read the values on-chain today:

  • USDC on Base mainnet: name USD Coin, version 2
  • USDC on Base Sepolia: name USDC, version 2

Copy a Sepolia config to mainnet without changing extra.name and every payment breaks.

Not every extra is a token domain. Circle Gateway batched payments sign against their own verifyingContract, so the token name check does not apply to those.

Trap 2: a long resource description kills payment, not only the listing

The resource block from your 402 comes back inside the client's payment payload. We had an endpoint with a 562 character description. The client signed fine. The facilitator answered 400 'paymentPayload' is invalid ... x402V1PaymentPayload requires 'scheme'. That message points at the payload. The real cause was the length. Cutting it to 406 characters made the same call settle at once. We now clamp every description to 500 characters.

Trap 3: amount is an integer string in atomic units

On EVM and Solana, "amount": "10000" means 0.01 USDC, because USDC has 6 decimals. "0.01" is wrong there, and a price meant for an 18 decimal token reads as a huge price in USDC. Some other networks use their own format, so check what yours expects.

Trap 4: mixing v1 and v2 names

v2 uses CAIP-2 network ids like eip155:8453, the field amount, and the PAYMENT-REQUIRED header. v1 uses base, maxAmountRequired, and the JSON body. A v2 answer with v1 names is matched by nobody. The same goes for clients: we found our own published samples still used v1 client imports, which fail on current installs.

Trap 5: junk payment headers

Send a malformed PAYMENT-SIGNATURE or X-PAYMENT header to your own endpoint. The right answer is 402. A 500 means bad input crashes your handler. A 200 means your paywall can be skipped. Only test this on endpoints you own.

Trap 6: changing the declared shape later

Bazaar discovery data rides in the signed requirements too. We once added fields to a declared output example and every endpoint on that service stopped verifying. Keep the declaration small and plain ASCII. Put rich docs in the response body and your OpenAPI file.

A 20 line self-check

This reads your 402 and flags traps 1 to 4. It never signs or pays.

import base64, json, sys, urllib.request, urllib.error USDC = {"eip155:8453": ("0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USD Coin", "2"), "eip155:84532": ("0x036cbd53842c5426634e7929541ec2318f3dcf7e", "USDC", "2")} try: urllib.request.urlopen(sys.argv[1], timeout=15); sys.exit("not a 402: paywall missing") except urllib.error.HTTPError as e: hv, body = e.headers.get("PAYMENT-REQUIRED"), e.read() print("status", e.code) req = json.loads(base64.b64decode(hv + "=" * (-len(hv) % 4))) if hv else json.loads(body) v = req.get("x402Version"); print("x402Version", v) desc = (req.get("resource") or {}).get("description", "") if v == 2 else "" if len(desc) > 500: print("FAIL description", len(desc), "chars") for i, a in enumerate(req["accepts"]): net, amt, ex = a.get("network"), a.get("amount", a.get("maxAmountRequired")), a.get("extra") or {} if v == 2 and ":" not in str(net): print(i, "FAIL v1 network name in v2:", net) if not str(amt).isdigit(): print(i, "FAIL amount not atomic integer:", amt) if net in USDC and str(a.get("asset")).lower() == USDC[net][0] and not ex.get("verifyingContract"): if (ex.get("name"), str(ex.get("version"))) != USDC[net][1:]: print(i, "FAIL extra domain", ex.get("name"), ex.get("version"), "want", USDC[net][1:]) print(i, "checked", net, amt) 

Run it with python3 check402.py https://your-api.example/paid-route.

Want a second pair of eyes

Our full checker also covers payTo sanity, timeouts, resource URL drift behind proxies, and the junk payment probe. Send your endpoint URL to x402@cyberwarex.com and we run it for free and send the report back. It is a script, not a person.

If you want a person to read your payment handler code as well, verify and settle order, replay, refunds on failed calls, what happens when the facilitator is down, that is a paid review for 20 USDC on Base, report in two days. Nothing is charged until you have seen the free report.

Use something else when

  • You need a formal smart contract audit. This is a review of an HTTP payment flow, not of on-chain code.
  • You use a hosted x402 middleware with default settings and have never changed the 402. Your first real settle will tell you if anything is off.
  • Your endpoint is already listed and settling. Then you have passed every check above.