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、Baseupto和訂單支付都有可公開開啟的 explorer 位址。 - Base
upto的簽名上限為95215atomic USDC,實際 settlement 為3atomic 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 回應一致。
