Introducing x402 v2

Dec 1, 2025

x402 v2 introduces a modular package structure, builder pattern registration, and a standardized extension system while maintaining backwards compatibility with v1 through the @x402/legacy package.

Resources

• x402 Whitepaper - Original protocol specification
• v2 Development Branch
• Public Roadmap

What’s New

Modular Package Structure

The Monolithic Package Has Been Split Into Focused Modules

• @x402/core - The payment protocol itself
• @x402/evm - Ethereum/EVM chains
• @x402/svm - Solana
• @x402/axios, @x402/fetch - HTTP clients
• @x402/express, @x402/hono, @x402/next - Server frameworks

Package Status

• ✅ @x402/core
• ✅ @x402/evm
• ✅ @x402/svm
• ✅ @x402/axios
• ✅ @x402/fetch
• ✅ @x402/express
• ✅ @x402/hono
• ✅ @x402/next
• ✅ @x402/extensions (Bazaar only)
• ✅ @x402/legacy (v1 compatibility)
• ❌ @x402/mcp (TODO)
• ❌ @x402/a2a (TODO)

Builder Pattern

Registration Now Uses Method Chaining Instead Of Config Objects

const client = new x402Client() .register("eip155:*", new ExactEvmScheme(wallet)) .register("solana:*", new ExactSvmScheme(wallet));

Adding chains is a simple .register() call per scheme.

Extension System

The core payment protocol remains simple, while extensions provide discovery, authentication, and custom metadata. Extensions are isolated in a dedicated namespace on payment objects, allowing new capabilities without breaking changes.

The first extension is Bazaar, which enables facilitator discovery and indexing of payment-enabled APIs.

Lifecycle Hooks

HTTP Payment Flows Have An Inherent Race Condition

• Verify payment ✅
• Do expensive work (generate AI image, run computation, etc.)
• Send response to user
• Settle payment on-chain ⚠️

If settlement fails after the response is sent, the work cannot be rolled back. v2 provides hooks to handle this:

app.use(paymentMiddleware({ "/api/generate": { price: "$0.10", ... } }, { onSettlementFailure: async ({ request, error }) => { await rollbackExpensiveWork(request.id); } }));

Dynamic Configuration

Pricing Can Be Computed Per-request

price: async (request) => { return request.query.tier === "premium" ? "$0.10" : "$0.01"; }

Payment Addresses Can Be Dynamic (useful For Marketplace Routing)

payTo: async (request) => { const seller = await getSellerForProduct(request.body.productId); return seller.address; }

Multiple payment options can be offered per endpoint.

Key Improvements

Developer Experience

v1 required knowing specific config field combinations for different networks, with errors surfacing at runtime. v2 uses the builder pattern with proper TypeScript types, surfacing errors at compile time and providing better IDE autocomplete.

Extensibility

Adding blockchain support in v1 required forking or upstreaming changes. In v2, new chains are added by implementing the scheme interface and calling .register(). The same pattern applies to payment schemes and business logic.

Multi-Chain Support

CAIP-2 network identifiers (eip155:8453 for Base, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp for Solana mainnet) are now used throughout the protocol. Cross-chain support is built into the architecture rather than added retroactively.

Technical Details

Protocol Changes

Wire Format Improvements

• Version field: x402Version: 2
• CAIP-2 network identifiers throughout
• Payment metadata in HTTP headers rather than response bodies
• accepted field indicating which payment option was used
• Fiat support via ISO 4217 codes (USD)

Testing

End-to-end Test Coverage Includes

• 6 server frameworks (Express, Hono, Gin, Next.js, FastAPI, Flask)
• 5 HTTP clients (axios, fetch, httpx, requests, Go net/http)
• EVM and Solana chains
• Extension system
• v1 backwards compatibility

An intelligent test minimizer reduces redundant test cases by 88.5%.

Language Support

Full implementations in TypeScript and Go, each following the idioms and patterns of their respective ecosystems.

Getting Started

Client

import { x402Client } from "@x402/axios"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; const wallet = privateKeyToAccount("0x..."); const client = new x402Client() .register("eip155:*", new ExactEvmScheme(wallet)); const data = await client.get("https://api.example.com/premium-data");

Server

import express from "express"; import { paymentMiddleware } from "@x402/express"; const app = express(); app.use(paymentMiddleware({ "/api/image": { price: "$0.10", payTo: "0x...", network: "eip155:8453" } })); app.post("/api/image", async (req, res) => { // Payment already verified by middleware const image = await generateImage(req.body.prompt); res.send(image); });

Migrating from v1

The @x402/legacy package provides v1 protocol compatibility for communicating with existing servers during migration.

Roadmap Status

Comparison Of Planned Roadmap Items Versus V2 Implementation

Roadmap Item v2 Status Notes MCP Support ❌ Spec only - foundation ready A2A Support ❌ Spec only - foundation ready Sign-In-With-X / Identity ❌ Spec only - extension system ready Bazaar Discovery ✅ Actually implemented Usage-Based Scheme (upto) ❌ Not present - only exact scheme Arbitrary Token Support ❌ Still EIP-3009 (USDC) focused Commerce Scheme (refunds/escrow) ❌ Not present XMTP Support ❌ Not present Facilitator Router ❌ Not present ERC-8004 Integration ❌ Not present

But v2 delivered features that weren’t on the roadmap:

Feature Description Modular Package Structure Split from monolithic @x402/x402 into focused packages Builder Pattern Registration client.register("eip155:*", new ExactEvmScheme()) Extension System Standardized way to add capabilities without breaking changes Hooks System Six lifecycle hooks for verification/settlement CAIP-2 Network Format eip155:8453 instead of base Dynamic Pricing Price as callback function Per-Route payTo Different payment addresses per endpoint Multiple Payment Options Array of payment configs per route HTTP Header Changes PAYMENT-SIGNATURE, PAYMENT-REQUIRED (base64 in header) Legacy Compatibility @x402/legacy package for v1 support

v2 provides the architectural foundation for roadmap features through its modular structure, extension system, and builder pattern, while delivering immediate improvements in developer experience and cross-chain support.