x402的v2版本

作者：YQ，编译：Block unicorn

x402 协议v2版本基于生产部署经验，代表着一次根本性的架构变革（有兴趣可以自行到 x402 的基金会观看：https://www.x402.org/writing/x402-v2-launch）。在处理了超过 1 亿笔交易后，团队识别出了关键的摩擦点，并围绕三个目标重新设计了协议：清晰的层级分离、与区块链无关的可扩展性以及符合 Web 标准。

v2版本中的变化

传统代理支付 vs x402代理支付

传统的支付流程需要多个手动步骤和人工干预。x402 通过实现自主、即时支付来消除了摩擦。

v2版本的架构改进

统一的支付接口

v2版本默认支持多链支付。单个 API 即可在 Base、Solana 或任何受支持的区块链上接受 USDC 支付，而无需修改代码。

网络标识符：采用CAIP-2

v1版本使用了自定义网络标识符，例如 “base-sepolia” 和 “base”。v2版本采用了 CAIP-2（链无关改进提案 2），格式为 "namespace:reference"。这使得它能够支持任何区块链，甚至非区块链支付系统。

支付需求重构

v1版本在每个支付选项中都重复了资源元数据。如果服务器接受了三种代币，它会重复三次 URL、描述和内容类型。v2版本将其提取到一个共享资源对象中，从而减小了消息大小并消除了不一致性。

扩展

v2版本引入了一个正式的扩展系统，用于独立于核心支付机制运行的可选功能。每个扩展都有一个包含扩展特定数据的 info 对象和一个通过 JSON Schema 定义结构的 schema 对象。

显式的支付选择

v1版本使用字段匹配启发式方法来确定客户端选择了哪个支付选项。v2版本通过一个包含完整所选支付要求的 “accepted” 字段，使选择过程更加明确。

HTTP传输更新

符合RFC 6648标准

IETF 弃用了 HTTP 标头的 “X-” 前缀，因为实验性标头往往会成为事实上的标准，但却始终被标记为实验性。v2版本移除了这些前缀，并将支付要求从响应体移至标头。为什么要移至标头？将协议元数据与应用程序内容分离，使得服务器能够为浏览器返回自定义 HTML 付费墙，同时在标头中保持机器可读的支付要求。这提高了中间件兼容性和框架集成性。

SDK重构

从硬编码到模块化

v1版本的SDK将区块链特定的逻辑嵌入到嵌套的 if/else 链中。添加新的区块链需要修改核心文件并发布新的SDK版本。v2版本引入了三个接口，实现了即插即用的区块链支持。

构建器模式注册

开发者使用 CAIP-2 通配符注册区块链实现。SDK 会根据网络模式将操作路由到正确的实现。通配符模式匹配：eip155:* 匹配所有 EVM 链 • solana:* 匹配所有 Solana 网络 • eip155:8453 特指 Base 主网

基于 Lambda 的策略引擎

v1版本中钱包类型和支付方案是硬编码的。v2版本引入了可组合的策略函数，用于运行时支付授权。

钩子系统

v1版本在验证之后、结算之前执行业务逻辑。如果结算失败，服务器已经执行了不可逆操作（文件传输、API 调用、数据库写入）。v2版本引入了六个生命周期钩子。

配置

v2版本中间件支持基于路由的配置，并提供回调函数以进行运行时决策。

Facilitator API 增强功能

能力通告

/support 端点现在通告三个关键功能：按协议版本分组的受支持支付类型、用于结算操作的签名地址以及已实现的扩展。

自动发现

发现扩展允许服务暴露结构化元数据以实现自动索引。Facilitator 可以抓取支持 x402 协议的端点，无需手动提交即可维护最新的价格目录。

迁移策略

v2版本通过命名空间隔离保持向后兼容性。facilitator 和服务器可以同时支持这两个版本。客户端通过 x402Version 字段指定版本偏好，实现会响应匹配的协议版本。