Adding x402 (Base) support to paylog.dev had more edge cases than I expected. This post documents the eight specific bugs I hit and how I fixed each one.
\nx402.org is a Base Sepolia testnet facilitator. Send it a Base mainnet payment and it returns invalid_payload every time, with no further explanation.
// sending a Base mainnet payment to x402.org\n{ "success": false, "error": "invalid_payload" }\nFor mainnet you need the CDP facilitator (https://api.cdp.coinbase.com/platform/v2/x402) plus a set of CDP API credentials (CDP_API_KEY_ID + CDP_API_KEY_SECRET).
x402-next@1.1.0 silently falls back to x402.org when facilitatorConfig is undefined. Easy to miss in production.
from fieldMy first implementation filtered Alchemy's alchemy_getAssetTransfers response like this:
// ❌ wrong\nconst CDP_FACILITATOR = '0x...'\nif (t.from.toLowerCase() !== CDP_FACILITATOR.toLowerCase()) continue\nHere is what EIP-3009 (Transfer With Authorization) actually does:
\ntransferWithAuthorization on-chain.from field is the user wallet, not the facilitator.Alchemy surfaces the ERC20 event's from directly, so t.from === user wallet. Since the Alchemy request already has fromAddress=wallet, the facilitator filter was redundant and was dropping every result.
services-x402.json is collected from the Bazaar / CDP discovery API, which returns network identifiers in CAIP-2 format ("eip155:8453"):
{ "network": "eip155:8453", "payTo": "0x..." }\nThe filter I had written expected the plain string "base":
// ❌ wrong\n.filter(e => e.network === 'base')\nAll 104 entries were filtered out. X402_SERVICE_MAP was completely empty and service names never resolved. It ran that way silently for days.
// ✅ fixed\nconst BASE_NETWORKS = new Set(['base', 'eip155:8453'])\n.filter(e => BASE_NETWORKS.has(e.network))\nsupported JWTThe CDP facilitator's supported endpoint is a GET, but I was signing the JWT with POST:
// ❌ wrong\nsupported: await makeHeader('/platform/v2/x402/supported') // defaults to POST\n\n// ✅ fixed\nsupported: await makeHeader('/platform/v2/x402/supported', 'GET')\nCDP's JWT auth embeds the request method in the token. A method mismatch causes an authentication error.
\ninvalidMessage gets silently droppedx402-next@1.1.0's VerifyError discards the invalidMessage field that CDP includes in verify failures. All you see is the string "invalid_payload" — no further context.
To surface the real message you need a proxy:
\nCDP_DEBUG=true → /api/v1/x402/cdp-proxy/[verify|settle|supported] → CDP\nThe proxy logs the full response:
\n[cdp-proxy/verify] invalidReason: invalid_payload\n| invalidMessage: transferWithAuthorization.from does not match expected payer\n| payer: 0x...\nuseFacilitator makes its own HTTP callsx402@1.1.0's useFacilitator fetches facilitatorConfig.url directly. There is no hook to intercept those requests from outside.
I spent time writing a cdpFetch wrapper inside route.ts with logging, only to discover it was never called. The fix was a proper proxy route at /api/v1/x402/cdp-proxy/[...path].
X402_RECIPIENT_ADDRESS silently burns revenueconst X402_RECIPIENT_ADDRESS = (\n process.env.X402_RECIPIENT_ADDRESS ?? '0x0000000000000000000000000000000000000000'\n) as `0x${string}`\nForget to set the environment variable and every payment goes to the zero address. The code runs without errors; the money is just gone.
\nPre-deploy checklist for Vercel:
\nX402_RECIPIENT_ADDRESS — your receiving addressCDP_API_KEY_ID + CDP_API_KEY_SECRET — Base mainnet authALCHEMY_API_KEY — Base RPC accessreq.url as the resource// ❌ static path — x402 client retries without query params\nconfig: { resource: '/api/v1/x402/report' }\n\n// ✅ pass the full request URL\nconfig: { resource: req.url as `${string}://${string}` }\nOn a 402 response the x402 client retries the request at the URL in the resource field. If resource is a static path, the retry arrives without ?wallet=0x... and the handler blows up on missing parameters.
| # | \nSymptom | \nRoot cause | \n
|---|---|---|
| 1 | \ninvalid_payload | \nx402.org is testnet-only | \n
| 2 | \nZero transfer logs | \nEIP-3009 from is the user wallet, not the facilitator | \n
| 3 | \nEmpty SERVICE_MAP | \nCAIP-2 "eip155:8453" vs plain "base" | \n
| 4 | \nJWT auth error | \nsupported endpoint requires GET, not POST | \n
| 5 | \nUndebuggable errors | \ninvalidMessage stripped by VerifyError | \n
| 6 | \nLogging wrapper never called | \nuseFacilitator bypasses custom fetch | \n
| 7 | \nZero revenue | \nX402_RECIPIENT_ADDRESS not set | \n
| 8 | \nParameters vanish on retry | \nStatic resource URL strips query string | \n
Server-side x402 has real sharp edges, but once it clicks the client side is genuinely pleasant — a few lines with @x402/fetch and payments just work.