跳转到主要内容
Ace Data Cloud X402 当前围绕 USDC 结算,支持 EVM 和 Solana 两类链。不同网络的签名方式、资产地址、gas 行为和适用场景不同,接入前需要先选好网络。

网络标识使用 CAIP-2

x402 v2 的 accepts[].network 是 CAIP-2 标识,不是 base、solana 这类简称。客户端匹配网络时必须按 CAIP-2 字符串比较:

支持矩阵

upto 目前只在 Base 上提供。实际可用项以 API 返回的 accepts 为准。你也可以查看 Facilitator:
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
Facilitator 验证签名后,会在链上调用 USDC 的 transferWithAuthorization 完成转账。 Base 是最推荐的正式接入网络,尤其适合 upto 后置计量,因为 Permit2、USDC 和钱包生态都更成熟。 Base exact 验证结果示例:
结果说明:
  • API paid retry 返回模型内容 ADC_BASE_E2E_OK。
  • 链上交易已在 BaseScan 可查,区块号是 46726299。
  • 95215 atomic USDC 对应 0.095215 USDC,是这次 API 调用的实际结算金额。
订单支付 Base exact 的程序运行结果:
结果说明:
  • 平台订单最终状态是 Finished。
  • 订单 pay_id 写入同一个 Base 交易哈希。
  • 1200000 atomic USDC 对应 1.2 USDC,是旧政策下该笔 10 Credits 订单的历史实付金额;新订单不再额外享受 X402 支付方式折扣,具体签名金额以本次 402 响应为准。

Solana

Solana 使用 SPL USDC TransferChecked。客户端会构造一笔转账交易,签名并提交,之后把交易签名或序列化交易放入 PAYMENT-SIGNATURE envelope。 Solana 的特点:
  • 使用 Solana wallet adapter 或 base58 secret key;
  • 资产是 Solana USDC mint;
  • 当前只支持 exact;
  • Facilitator 会校验 transfer instruction 的 mint、destination、authority 和 amount。
如果使用钱包 fee payer 模式,钱包会直接提交交易,Facilitator 负责确认交易并返回 settlement 结果。 Solana 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 为准。