jakiro
Author:YQ,compile：Block unicorn
The v2 version of the x402 protocol is based on production deployment experience and represents a fundamental architectural change (if you are interested, you can go to the x402 foundation to watch: https://www.x402.org/writing/x402-v2-launch).After processing more than 100 million transactions, the team identified key friction points and redesigned the protocol around three goals: clear layer separation, blockchain-agnostic scalability, and compliance with web standards.
Changes in v2 version
Traditional agency payment vs x402 agency payment
Traditional payment processes require multiple manual steps and human intervention.x402 removes friction by enabling autonomous, instant payments.
Architectural improvements in v2 version
Unified payment interface
The v2 version supports multi-chain payment by default.A single API to accept USDC payments on Base, Solana, or any supported blockchain without modifying your code.
Network identifier: using CAIP-2
The v1 version uses custom network identifiers such as “base-sepolia” and “base”.The v2 version adopts CAIP-2 (Chain-Independent Improvement Proposal 2), and the format is “namespace:reference”.This enables it to support any blockchain, even non-blockchain payment systems.
Payment demand reconstruction
The v1 version has resource metadata duplicated in each payment option.If the server accepts three tokens, it repeats the URL, description, and content type three times.The v2 version extracts it into a shared resource object, reducing message size and eliminating inconsistencies.
Expand
Version v2 introduces a formal extension system for optional functionality that operates independently of the core payment mechanism.Each extension has an info object that contains extension-specific data and a schema object that defines the structure via JSON Schema.
Explicit payment options
The v1 version uses field matching heuristics to determine which payment option was selected by the client.Version v2 makes the selection process clearer with an “accepted” field containing the complete selected payment requirements.
HTTP transfer update
Complies with RFC 6648 standard
The IETF deprecated the “X-” prefix for HTTP headers because experimental headers tend to become de facto standards but are always marked as experimental.Version v2 removes these prefixes and moves the payment requirement from the response body to the header.Why move to header?Separating protocol metadata from application content enables servers to return custom HTML paywalls to browsers while maintaining machine-readable payment requirements in the header.This improves middleware compatibility and framework integration.
SDK refactoring
From hard coding to modularity
The v1 version of the SDK embeds blockchain-specific logic into nested if/else chains.Adding a new blockchain requires modifying core files and releasing a new SDK version.The v2 version introduces three interfaces to achieve plug-and-play blockchain support.
Builder pattern registration
Developers register blockchain implementations using CAIP-2 wildcards.The SDK routes operations to the correct implementation based on the network mode.Wildcard pattern matching:eip155:*Matches all EVM chains •solana:*Matches all Solana networks• eip155:8453Specifically refers to the Base mainnet
Lambda-based strategy engine
Wallet type and payment scheme are hard-coded in v1.Version v2 introduces composable policy functions for runtime payment authorization.
hook system
The v1 version executes business logic after verification and before settlement.If settlement fails, the server has performed an irreversible operation (file transfer, API call, database write).The v2 version introduces six life cycle hooks.
Configuration
The v2 version of the middleware supports route-based configuration and provides callback functions for runtime decisions.
Facilitator API enhancementFunction
Capability Notice
The /support endpoint now advertises three key features: supported payment types grouped by protocol version, signing addresses for settlement operations, and implemented extensions.
autodiscover
Discovery extensions allow services to expose structured metadata for automatic indexing.FacilitatorEndpoints supporting the x402 protocol can be scraped to maintain an up-to-date price catalog without manual submission.
Migration strategy
The v2 version maintains backward compatibility through namespace isolation.facilitatorand servers can support both versions simultaneously.The client specifies a version preference via the x402Version field, and the implementation responds with a matching protocol version.
