Author:YQ,Compiled by: Block unicorn

The x402 protocol v2 version, based on production deployment experience, represents a fundamental architectural change (those interested can visit the x402 Foundation website: https://www.x402.org/writing/x402-v2-launch).
The x402 protocol v2 version, based on production deployment experience, represents a fundamental architectural change (those interested can visit the x402 Foundation website for more information: https://www.x402.org/writing/x402-v2-launch).
... After processing over 100 million transactions, the team identified key friction points and redesigned the protocol around three goals: clear hierarchical separation, blockchain-agnostic scalability, and compliance with Web standards.

Changes in version v2

Traditional agent payment vs x402 agent payment

v2 version architecture improvements
Unified payment interface
v2 version supports multi-chain payments by default. A single API can accept USDC payments on Base, Solana, or any supported blockchain without modifying the code.

Network Identifier: Adopting CAIP-2
Version 1 used custom network identifiers, such as “base-sepolia” and “base”. Version 2 adopts CAIP-2 (Chain-Independent Improvement Proposal 2), in the format "namespace:reference". This allows it to support any blockchain, even non-blockchain payment systems.

Payment Requirement Restructuring
Version 1 repeated resource metadata in each payment option. If the server accepted three tokens, it would repeat the URL, description, and content type three times. Version 2 extracts this into a shared resource object, thereby reducing message size and eliminating inconsistencies.

Extensions
Version 2 introduced a formal extension system for optional functionality that operates independently of the core payment mechanism. Each extension has an info object containing extension-specific data and a schema object whose structure is defined via JSON Schema.
...

Explicit Payment Selection
Version 1 used a field matching heuristic to determine which payment option the client selected. Version 2 makes the selection process more explicit through an "accepted" field that contains the complete requirements of the selected payment.

HTTP Transport Update
Compliant with RFC 6648
The IETF deprecated the "X-" prefix in HTTP headers because experimental headers often became de facto standards but were always marked as experimental. Version 2 removed these prefixes and moved the payment request from the response body to the header. Why move it to the header? Separating protocol metadata from application content allows servers to return custom HTML paywalls to browsers while maintaining machine-readable payment requests in the header. This improves middleware compatibility and framework integration. The v1 SDK embedded blockchain-specific logic into nested if/else chains. Adding a new blockchain required modifying the core files and releasing a new SDK version. Version v2 introduced three interfaces, enabling plug-and-play blockchain support.

Builder Pattern Registration
Developers use CAIP-2 wildcards to register blockchain implementations. The SDK will route operations to the correct implementation based on the network pattern.
Developers use CAIP-2 wildcards to register blockchain implementations. The SDK will route operations to the correct implementation based on the network pattern.

Developers use CAIP-2 wildcards to register blockchain implementations. The SDK will route operations to the correct implementation based on the network pattern.


Configuration
The v2 version middleware supports route-based configuration and provides callback functions for runtime decisions.The v2 version middleware supports route-based configuration and provides callback functions for runtime decisions.

Facilitator API EnhancementFeatures
Capability Announcement
/support endpoint now announces three key features: supported payment types grouped by protocol version, signature addresses for settlement operations, and implemented extensions.

Auto Discovery
Discovery extensions allow services to expose structured metadata for automatic indexing. Facilitator can crawl endpoints that support the x402 protocol, maintaining the latest price catalog without manual submission.It can crawl endpoints that support the x402 protocol, maintaining the latest price catalog without manual submission.

Migration Strategy
Version v2 maintains backward compatibility through namespace isolation.facilitatorBoth the server and client can support both versions simultaneously. Clients specify version preferences through the x402Version field, and the implementation will respond with the matching protocol version.


