# Migrating a live x402 service from V1 to V2 on Base mainnet

> Source: <https://dev.to/ukenal/migrating-a-live-x402-service-from-v1-to-v2-on-base-mainnet-1mg9>
> Published: 2026-07-23 21:53:13+00:00

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](https://github.com/ukenal/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:

``` js
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`

.

``` js
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:

``` js
// 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:

``` python
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`

middleware`payment-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*