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 響應一致。