网络标识使用 CAIP-2
x402 v2 的accepts[].network 是 CAIP-2 标识,不是 base、solana 这类简称。客户端匹配网络时必须按 CAIP-2 字符串比较:
支持矩阵
upto 目前只在 Base 上提供。实际可用项以 API 返回的 accepts 为准。你也可以查看 Facilitator:
/supported 的返回:
- Base 和 Solana 的
exact是固定金额支付路径。 - 只有 Base 提供
upto后置计量路径,依赖 Permit2 approve。 upto条目里的extra.facilitatorAddress是客户端签名时要写入 witness 的地址,必须和服务端返回值一致。
Base
Base 使用官方 USDC 合约:exact 方案中,客户端签署 EIP-712 TransferWithAuthorization。签名内容包括:
from:付款钱包地址to:Ace Data Cloud 收款地址value:本次支付金额validAfter/validBefore:签名有效时间窗口nonce:32 字节随机 nonce
transferWithAuthorization 完成转账。
Base 是最推荐的正式接入网络,尤其适合 upto 后置计量,因为 Permit2、USDC 和钱包生态都更成熟。
Base exact 验证结果示例:
- API paid retry 返回模型内容
ADC_BASE_E2E_OK。 - 链上交易已在 BaseScan 可查,区块号是
46726299。 95215atomic USDC 对应0.095215USDC,是这次 API 调用的实际结算金额。
exact 的程序运行结果:
- 平台订单最终状态是
Finished。 - 订单
pay_id写入同一个 Base 交易哈希。 1200000atomic USDC 对应1.2USDC,是旧政策下该笔 10 Credits 订单的历史实付金额;新订单不再额外享受 X402 支付方式折扣,具体签名金额以本次 402 响应为准。
Solana
Solana 使用 SPL USDCTransferChecked。客户端会构造一笔转账交易,签名并提交,之后把交易签名或序列化交易放入 PAYMENT-SIGNATURE envelope。
Solana 的特点:
- 使用 Solana wallet adapter 或 base58 secret key;
- 资产是 Solana USDC mint;
- 当前只支持
exact; - Facilitator 会校验 transfer instruction 的 mint、destination、authority 和 amount。
exact 验证结果示例:
- paid retry 已经返回 HTTP 200,并且模型输出
ADC_SOLANA_E2E_OK。 - 公开 RPC 查询链上 signature 时可能遇到限流。
- 因为公开 RPC 查询可能限流,这里不写 Solana explorer。需要严格对账时,请使用自有 Solana RPC 或平台侧结算记录确认交易签名。
如何选择
无论选择哪条链,都不要在客户端硬编码价格。价格由服务器返回的
accepts[].maxAmountRequired 决定。
新增 EVM 网络
以下网络的原生 USDC 固定金额支付已提供代码支持,按网络逐一开放。 是否可用以订单或 API 返回的accepts 为准;不代表所有网络已在生产启用。
这些网络仅支持
exact,币种精度为 6。不要使用同名的桥接 USDC。
使用官方 TypeScript/Python X402 Client 时,可以传入表中的简称或 CAIP-2 标识。
客户端使用目标链 ID 构造签名;钱包必须支持目标网络。
Phantom 扩展钱包的官方支持表列出了 Arbitrum 和 Polygon;Optimism、Avalanche
目前未列入该表,可使用支持目标链的 Rabby 或 MetaMask。EVM 地址可以在不同链上相同,
但余额互相独立,Solana 地址不适用于 EVM USDC。
参见 Phantom 钱包支持表。
新网络灰度入口
新链入口默认隐藏。访问控制台或 Studio 时,可用?features=x402-arbitrum
开启对应链,多个 flag 用逗号分隔。关闭单链使用 ?features=-x402-arbitrum,
清除本机覆盖使用 ?features=none。每个域名分别保存开关。
订单报价和付款重试使用相同开关,服务端会独立校验;已有付款记录仍可查看。
仅开启页面 flag 不会启用尚未配置的链,具体可支付网络仍以实时 accepts 为准。
