accepts 裡有什麼、PAYMENT-SIGNATURE 又是怎樣讓同一個 API 請求變成已付款請求的。
準備工作
你需要準備:
X402 呼叫 Ace Data Cloud API 時不需要 API Token。SDK 第一次請求不帶
Authorization,Gateway 會回傳 402 Payment Required 和付款要求;SDK 簽名後自動重試。
安裝 SDK
原始碼和套件位址:- SDK 儲存庫:https://github.com/AceDataCloud/SDK
- X402 Client 儲存庫:https://github.com/AceDataCloud/X402Client
- npm:
@acedatacloud/sdk、@acedatacloud/x402-client - PyPI:
acedatacloud、acedatacloud-x402
acedatacloud-x402 中。
乾淨暫存環境的安裝和匯入檢查輸出:
- npm 套件和 PyPI 套件都是真實發佈套件,不是文件裡的佔位名稱。
acedatacloud-x402[cli]會安裝 CLI,approve-permit2子命令可用於upto情境的 Permit2 授權。
第一次請求會回傳 402
你可以先用curl 看看未付款請求回傳什麼。下面範例不會產生扣款,因為它沒有攜帶 PAYMENT-SIGNATURE:
accepts 陣列,常見結構如下:
PAYMENT-REQUIRED 回應標頭中,方便用戶端不解析 body 就讀取付款要求。
正式環境 API 未付款請求的程式輸出摘要如下:
- 第一次請求沒有攜帶
Authorization或PAYMENT-SIGNATURE,所以回傳 HTTP 402,不會產生扣款。 accepts是本次請求唯一可信的簽名依據,包含可選網路、scheme、金額上限、收款地址和資產地址。network是 CAIP-2 識別碼,用戶端選網時必須按 CAIP-2 字串比對。- 這次
gpt-4o-mini最小聊天請求的上限金額是95215atomic USDC,也就是0.095215USDC。 - 每次請求都應該讀取當次 402 回應,不要把範例金額硬編碼進業務程式碼。
用 SDK 完成付款重試
下面是最小 TypeScript 範例。它指定network: 'base',handler 會從本次 402 回應中選擇 Base 的 payment requirement;實際金額和收款地址仍以 accepts 為準:
- SDK 發送一次一般 API 請求,不帶
Authorization。 - Gateway 回傳
402 Payment Required和accepts。 createX402PaymentHandler選擇network = 'base'的 payment requirement 並簽出PAYMENT-SIGNATURE。- SDK 用同一個請求主體重試,Gateway 呼叫 Facilitator 驗證並結算後放行到目標 API。
查看 Facilitator 支援能力
X402 API 不依賴資源目錄。用戶端直接呼叫已知 API,並以該請求即時回傳的402 Payment Required 和 accepts 作為唯一價格與簽名依據。
Facilitator 的能力聲明位於:
/supported、/verify、/settle 和目前啟用的支付網路,不列出 API 資源。
Ace Data Cloud 的生產 Facilitator 位址為:
kinds 會列出 Facilitator 支援的網路和 scheme。實際呼叫時仍以 API 回傳的 accepts 為準。
Facilitator /supported 輸出:
/supported說明 Facilitator 具備這些網路和 scheme 的驗證、結算能力。- Base 和 Solana 都支援
exact;upto目前只在 Base 上提供。 - 具體 API 是否允許某個網路,仍以該 API 的 402
accepts為準。

