Field notes from migrating a live, payment-gated API from x402 V1 to V2 on Base mainnet — the undocumented gotchas, working code from a service in production, and a checklist at the bottom.
Written from x402ai, which settles real USDC on Base via the Coinbase CDP facilitator. Every code sample here is running in production, not reconstructed from the spec.
Last verified: July 2026 · @x402/*
2.19.0 · @coinbase/x402
2.1.0
In a hurry? → Migration checklist
If you built an x402 service before mid-2026, you're on V1. You may not have noticed, because V1 services keep serving 402s and keep settling payments. Nothing crashes. The migration pressure comes from two directions instead:
Discovery rejects you. Submitting a V1 origin to x402scan returns, in effect, "x402 v1 response detected — migrate to v2 spec", plus a second complaint about the absence of a discovery document. Since x402scan is where autonomous agents actually find services, a V1 service is invisible to the thing that generates traffic.
Agents are already failing against you silently. Check your logs for invalid_payload
errors you never explained. Those are V2-capable clients attempting payment against V1 middleware and bouncing. You've been losing real requests, and the error message doesn't say why.
That second one is the part I'd flag hardest. I had those errors in my logs for weeks and filed them mentally as noise.
Five things, in rough order of how much time they'll cost you:
x402-hono
is frozen at 1.2.0. The live line is the scoped @x402/*
namespace.payment-required
header.eip155:8453
rather than the old string form.X-Forwarded-Proto
is ignored.http://
unless you set them explicitly.This tripped me up before I wrote a line of code, because searching for x402 packages surfaces the frozen ones first.
Frozen (V1): x402-hono
@ 1.2.0 — final release, do not build on it.
Live (V2): the scoped namespace —
@x402/hono
(or your framework's equivalent)@x402/core
@x402/evm
@x402/extensions
@coinbase/x402
— for CDP facilitator configAt time of writing the @x402/*
packages were at 2.19.0 and @coinbase/x402
at 2.1.0. Check current versions; this line moves.
npm install @x402/hono@2 @x402/core@2 @x402/evm@2 @coinbase/x402@2 --legacy-peer-deps
You will likely need --legacy-peer-deps
. The optional paywall peer dependency wants React 19; if your project is on React 18 (or has any other React in the tree), npm refuses the install outright. The paywall is optional and unrelated to server-side payment gating, so the flag is safe here — but know why you're using it rather than reflexively adding it.
Before (V1): middleware took a routes object and a facilitator, with auth headers you assembled yourself.
After (V2): you build a resource server, register a scheme against a network, then hand that to the middleware.
This cost me time before a single line of logic ran. The V2 packages use subpath exports, and the obvious top-level import is not the one you want:
import { paymentMiddleware } from '@x402/hono'
import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server'
import { createFacilitatorConfig } from '@coinbase/x402'
import { ExactEvmScheme } from '@x402/evm/exact/server'
@x402/core/server
, not @x402/core
. @x402/evm/exact/server
, not @x402/evm
.
const facilitatorClient = new HTTPFacilitatorClient(
createFacilitatorConfig(
process.env.CDP_API_KEY_NAME,
process.env.CDP_API_KEY_PRIVATE_KEY
)
)
const resourceServer = new x402ResourceServer(facilitatorClient)
.register('eip155:8453', new ExactEvmScheme())
const routes = {
'POST /api/embed': {
accepts: {
scheme: 'exact',
price: prices['/api/embed'],
network: 'eip155:8453',
payTo: process.env.WALLET_ADDRESS,
},
resource: new URL('/api/embed', baseUrl).toString(),
description: 'Text embeddings (768-dim) via nomic-embed-text. POST {input: string}.',
mimeType: 'application/json',
},
// ...one entry per paid route
}
return paymentMiddleware(routes, resourceServer)
register()
is fluent — it returns the resource server, so it chains off the constructor.
V1 nested description
under a config
key — and silently ignored a top-level description
, which is a fun thing to discover after wondering why your route descriptions never showed up anywhere.
V2 keys routes by METHOD /path
, takes accepts
as a single object rather than an array, and puts description
and mimeType
at the top level as siblings of accepts
.
If you were on CDP's facilitator under V1, there's a decent chance you did what I did: imported generateJwt
through @coinbase/cdp-sdk
's internal _cjs
path via createRequire
, then hand-built auth headers on every request.
That was never supported. It worked, but it depended on the internal module layout of someone else's package.
createFacilitatorConfig(apiKeyId, apiKeySecret)
from @coinbase/x402
is the supported replacement. The entire hack — the createRequire
shim, the internal import, the createAuthHeaders
function — deletes cleanly. This was the single most satisfying part of the migration and the strongest argument for doing it even if discovery weren't forcing your hand.
https
gotcha — and the workaround you can now delete
Under V1, if you terminated TLS upstream (Cloudflare tunnel, nginx, anything), the middleware saw the internal request as plain HTTP and advertised your resource URLs as http://
. The standard fix was middleware that injected forwarded headers:
// V1-era workaround
app.use('*', async (c, next) => {
c.req.raw.headers.set('X-Forwarded-Proto', 'https')
c.req.raw.headers.set('X-Forwarded-Host', baseUrl.host)
await next()
})
V2 ignores those headers. So the workaround silently stops doing anything, your resource URLs revert to http://
, and the middleware that was supposed to prevent exactly that is still sitting in your file looking load-bearing.
The V2 fix is the explicit resource
field per route, shown above. Runtime resolution is effectively routeConfig.resource || adapter.getUrl()
— anything you set explicitly wins, anything you don't falls back to the derived (wrong) URL. Set it on every paid route; there is no global override.
Once that's in place, delete the forwarded-header middleware. I still had mine months after the migration, which is how this section came to be written.
This is where people think the migration broke something.
A correct V2 402 returns an empty JSON body — literally {}
. The challenge lives in the payment-required
response header, base64-encoded. If you're used to V1's body-carried challenge, an empty body reads like a bug.
To check it:
curl -s -i -X POST https://your-api.example/api/endpoint \
-H "Content-Type: application/json" \
-d '{"input":"check"}' \
| grep -i payment-required \
| sed 's/payment-required: //' | tr -d '\r' | base64 -d | jq .
You're looking for x402Version: 2
, your CAIP-2 network (eip155:8453
for Base mainnet), the correct asset and payTo
address, and a resource
field that starts with https://
.
Neither is required by V2, but both are easier to do during a migration than to retrofit.
Validate input before the payment gate. Register your validation middleware ahead of the payment middleware so a malformed request gets a
400
instead of a 402
. Otherwise you're asking an agent to pay before you tell it the request was never going to work — which is bad behavior, and worse when the payer is an automated client with no human to notice.Guard the startup window. The payment handler is built asynchronously (it constructs a facilitator client), so there's a window where the server can accept connections before the handler exists. A delegate middleware that returns 503 service initializing
until the handler resolves is cheap insurance against serving unprotected routes during a restart.
The client rewrite is smaller than the server one, and the same subpath trap applies:
from x402 import x402ClientConfig, SchemeRegistration
from x402.mechanisms.evm.exact.client import ExactEvmScheme
from x402.http.clients.requests import wrapRequestsWithPaymentFromConfig
config = x402ClientConfig(
schemes=[
SchemeRegistration(
network="eip155:8453",
client=ExactEvmScheme(signer=account),
),
],
)
session = wrapRequestsWithPaymentFromConfig(requests.Session(), config)
resp = session.post(ENDPOINT, json={"input": "..."}, timeout=90)
That's the entire integration. The wrapper handles the whole dance — sends the unpaid request, receives the 402, decodes the header challenge, signs the EIP-3009 authorization, retries. You never hand-parse a challenge.
Symmetric with the request side, and easy to miss: on success, settlement details come back base64-encoded in an X-PAYMENT-RESPONSE
header (some stacks emit payment-response
— check both). Decode it for the transaction hash:
settle = resp.headers.get("X-PAYMENT-RESPONSE") or resp.headers.get("payment-response")
info = json.loads(base64.b64decode(settle))
print(f"https://basescan.org/tx/{info.get('transaction')}")
If you're logging anything about payments, that header is where the on-chain proof lives.
Worth stating plainly because it surprises people: EIP-3009 is gasless for the payer. The buyer signs a transfer authorization; the facilitator submits and pays gas. A payer wallet needs USDC on Base and nothing else — no ETH, ever.
This is also why a legitimate agent wallet can show zero self-submitted transactions on a block explorer while having successfully paid you many times. When I got my first payment from an unfamiliar address, its transaction history was empty, which reads as suspicious until you remember the payer never submits anything.
Keep your V1 client around as a .bak
until the V2 one settles. Mine earned its keep.
Migrating to V2 isn't sufficient for x402scan. It also wants a discovery document, and in practice /openapi.json
is what gets crawled.
An OpenAPI 3.1 document, served before your payment gate, with per-endpoint payment metadata:
x-payment-info
carrying a fixed decimal USD amount (0.010000
, not 0.01
— use consistent decimal precision)protocols: [{ x402: {} }]
/health
, discovery routes) marked security: []
Three things I'd flag:
Match your response field names to your actual handlers. My OpenAPI advertised generic field names while the handlers returned embedding
, summary
, and answer
. A crawler probing the documented shape gets a mismatch.
Unify your request field names before you publish the spec. My three endpoints had grown independently and took input
, text
, and question
respectively — while the OpenAPI doc advertised input
for all three. Two of the three would have failed any automated probe. Standardizing on one field name across every endpoint is worth doing regardless; a public spec makes it mandatory.
Two different price representations coexist, and it's easy to mix them up. The V1-shaped /.well-known/x402
manifest expresses price in atomic token units as a string — '10000'
for $0.01 USDC, which has six decimals. The OpenAPI x-payment-info
block expresses it as decimal USD — '0.010000'
. Same price, two encodings, and no error if you put the wrong one in the wrong place.
Worth noting: my /.well-known/x402
manifest was still V1-shaped (x402Version: 1
, network: 'base'
rather than eip155:8453
) at registration time and nothing complained, because registration went through /openapi.json
. If you're short on time, prioritize the OpenAPI doc — but know you're carrying a stale manifest.
The CDP facilitator has a minimum price floor. Price anything below it and settlement fails. I ended up at $0.01 / $0.02 / $0.04 across three endpoints, which sits just above it. If your business model assumed sub-cent pricing, verify against the current floor before building around it.
** x402.org's facilitator is testnet-only.** It's the obvious default when you're reading the spec, and it will not settle on mainnet. For Base mainnet you need CDP's, or another mainnet-capable facilitator.
invalid_payload
errors in your logs)@x402/*
scoped packages with --legacy-peer-deps
@x402/core/server
, @x402/evm/exact/server
HTTPFacilitatorClient
→ x402ResourceServer
→ .register('eip155:8453', new ExactEvmScheme())
→ paymentMiddleware
createFacilitatorConfig
accepts
object, sibling description
/mimeType
resource
field per paid route (fixes http://
)X-Forwarded-Proto
middlewarepayment-required
header, not the body.bak
X-PAYMENT-RESPONSE
header/openapi.json
, before the payment gateDo the OpenAPI document first, even before the code migration. It forces you to confront your API's inconsistencies — mismatched field names, undocumented response shapes, endpoints that grew independently — while you can still fix them freely. I did it last and had to go back and standardize things I'd have caught earlier.
And migrate before you need to. The V1 stack still works right up until the moment discovery matters, and by then you're doing an urgent migration instead of a calm one.
Written by Landy Ukena. I run x402ai — three payment-gated AI inference endpoints on Base mainnet, self-hosted and settling real USDC via the Coinbase CDP facilitator. LinkedIn