跳轉到主要內容
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 和 Solana 的可用支付方式。
  • accepts[].network 是 CAIP-2 識別碼,客戶端選擇網路時必須依 CAIP-2 字串比對。
  • TypeScript SDK 與 Python SDK 都能自動處理 402 並完成已支付重試。
  • Base 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 回應一致。