Skip to main content
X402 是基于 HTTP 402 Payment Required 的链上支付协议。通过 Ace Data Cloud 的 X402 能力，调用方可以不创建 API Token、不预充值账户余额，而是在每一次 API 请求中直接用 USDC 完成链上支付。 这组文档按真实接入顺序组织：先跑通一次最小请求，再接入 SDK，之后理解网络、计费方案、订单支付和 Facilitator。建议按下表从上到下阅读。

​
推荐接入路径

如果你只是想调用 Ace Data Cloud API，优先使用官方 SDK：
  • TypeScript：@acedatacloud/sdk + @acedatacloud/x402-client
  • Python：acedatacloud + acedatacloud-x402
公开源码与包地址： SDK 会自动完成第一次无认证请求、解析 402 Payment Required、调用 payment handler、携带 PAYMENT-SIGNATURE 重试这些步骤。你只需要准备一个有 USDC 的钱包，并选择希望使用的网络。 如果你要让自己的 API 也支持 X402 收款，则需要阅读 Facilitator 文档，理解 paymentRequirements、paymentPayload、/verify 和 /settle 的关系。

​
支持状态

Ace Data Cloud X402 已在公开 API、官方 SDK、Facilitator 和链上结算路径完成验证。下表按开发者接入时最常用的能力维度汇总当前状态。 以下输出仅用于说明已验证路径的返回形态。实际接入时，请始终以当前 API 返回的 accepts 为准。
说明：
  • npm 和 PyPI 包都已在干净环境安装并导入成功。
  • 未支付 API 请求返回 402，accepts 中包含 Base、SKALE 和 Solana 的可用支付方式。
  • accepts[].network 是 CAIP-2 标识，客户端选网时必须按 CAIP-2 字符串匹配。
  • TypeScript SDK 与 Python SDK 都能自动处理 402 并完成 paid retry。
  • Base exact、SKALE exact、Base upto 和订单支付都有可公开打开的 explorer 地址。
  • Base upto 的签名上限为 95215 atomic USDC，实际 settlement 为 3 atomic USDC，体现了后置计量按真实用量结算的特性。
  • Solana exact 已验证 HTTP 402 -> HTTP 200 和模型输出。由于公开 RPC 查询可能限流，严格对账时建议使用自有 Solana RPC 或平台侧结算记录确认交易签名。

​
接入注意事项

开发者接入时，请优先关注当前请求返回的实时支付要求，而不是复制文档中的示例金额或地址：
  • accepts[].maxAmountRequired 是当前请求可签名的最大金额。
  • accepts[].asset 是本次请求要使用的 USDC 合约或 mint。
  • accepts[].extra.chainId、accepts[].extra.facilitatorAddress 和 accepts[].extra.verifyingContract 会参与 EVM typed data 签名。
  • upto 需要钱包先对目标链 USDC 授权 Permit2；未授权时会返回 PERMIT2_ALLOWANCE_REQUIRED。
  • 如果明确希望使用后置计量，请在 TypeScript SDK 中传入 preferScheme: 'upto'，否则 SDK 会选择该网络下服务器返回的第一个可用 requirement。

​
可以公开核验的范围

接入前可以先核验这些公开入口和 SDK 行为：
  • 未带 Authorization 或 PAYMENT-SIGNATURE 的 API 请求会返回 402 Payment Required，响应中的 accepts 是本次请求的唯一签名依据。
  • TypeScript SDK 和 Python SDK 都提供 payment handler，SDK 传输层在收到 402 后会调用 handler 并重试一次。
  • https://facilitator.acedata.cloud/.well-known/x402：返回 Facilitator 支持的网络、scheme 与协议端点；API 价格仍以目标请求实时返回的 402 为准。
  • https://facilitator.acedata.cloud/supported：返回 Facilitator 支持的网络与 scheme。
  • X402Client 仓库包含高级链上验证工具，可用于确认签名、重试和 settlement 行为；工具输出不替代线上 API 返回的 accepts。
upto 属于后置计量结算，适合聊天补全、模型调用等真实用量在响应后才知道的 API。当前只有 Base 提供 upto；如果签名验证失败，请检查 chain id、facilitator 地址、spender、USDC 合约和 Permit2 allowance 是否与 402 响应一致。