跳轉到主要內容
X402 涉及 HTTP、SDK、簽名、Facilitator 和鏈上交易。排查簽名或結算問題時,建議依「公開入口 -> 402 回應 -> SDK payment handler -> 鏈上 settlement」的順序逐層確認。本教學說明各層的檢查方式,並列出常見錯誤。

檢查公開入口

Facilitator 能力聲明:
如果回傳 facilitator、supportedKinds 和協議端點,表示能力中繼資料正常。API 資源探索已退役;請直接呼叫目標 API,並以即時 402 回應為準。 Facilitator 支援能力:
如果回傳 kinds,表示 Facilitator 入口正常。

檢查 402 accepts

傳送一個不會扣款的未驗證請求:
檢查回傳的 accepts 中是否包含你要使用的網路。network 是 CAIP-2 識別碼:
  • eip155:8453 + exact(Base)
  • eip155:8453 + upto(Base,後置計量)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact(Solana)
如果沒有目標網路,表示該 API 或目前環境沒有設定對應的 X402 收款方式。

執行 X402Client 進階驗證工具

X402Client 儲存庫提供進階驗證工具,可用於確認 402 回應選擇、簽名產生、paid retry 和鏈上 settlement。它們需要 funded wallet、RPC、私鑰和開發依賴。一般業務整合建議優先使用 TypeScript 或 Python SDK;只有在需要定位簽名或鏈上結算問題時,再執行這些工具。 儲存庫位址:https://github.com/AceDataCloud/X402Client
Base:
Solana:
驗證工具通常會印出:
  1. 第一次請求的 402 回應。
  2. 選取的 payment requirement。
  3. 簽名後的 PAYMENT-SIGNATURE 摘要。
  4. 重試後的 HTTP 狀態和回應本文。
  5. 鏈上 settlement transaction,或失敗時的 Facilitator 錯誤原因。
不要將私鑰或完整 PAYMENT-SIGNATURE 發送到日誌系統或工單中。 公開 API 驗證結果範例:
說明:
  • Base exact、Solana exact 和 Base upto 都完成了 HTTP 402 到 HTTP 200 的 paid retry。
  • Base exact 的鏈上交易已可在 BaseScan 查詢,結算金額為 95215 atomic USDC。
  • Base upto 的簽名上限為 95215 atomic USDC,但實際鏈上 settlement 為 3 atomic USDC,表示後置計量依實際用量扣款。
  • Solana 路徑已確認 paid retry 和模型輸出。公開 RPC 可能會限流;需要嚴格鏈上對帳時,請使用自有 Solana RPC 或平台端結算紀錄確認交易簽名。

SDK smoke test

進階驗證工具用於檢查簽名和鏈上結算。業務端還應執行 SDK smoke test,確認應用程式碼能夠透過 payment handler 自動處理 402。以下只展示核心片段,完整程式碼需要補齊錢包、provider 和 import。 TypeScript:
Python:
如果模型依要求回傳固定字串,表示 SDK、payment handler、Gateway、Facilitator 和目標 API 已串接完成。 上面兩段 smoke test 使用 Base exact,依 402 報價的固定金額結算。聊天補全屬於依 token 計量的情境,正式整合時建議傳入 preferScheme: 'upto'(Python 為 prefer_scheme="upto"),依實際用量結算。 Python SDK 回傳物件是 dict,可使用 res["choices"][0]["message"]["content"] 讀取內容。

訂單支付 E2E

訂單支付使用 platform.acedata.cloud 的平台 API,需要平台帳戶權杖。完整流程為:建立 Pending 訂單,POST /api/v1/orders/{order_id}/pay/ 觸發 402,然後帶著 PAYMENT-SIGNATURE 重試。 小額訂單支付驗證結果範例:
以下交易紀錄為舊政策下的歷史實測樣本,金額和交易雜湊保留原樣。新的 X402 訂單不再提供支付方式折扣;請以本次 402 回應的 amount 作為簽名和付款依據。
結果說明:
  • 建立訂單後,訂單狀態是 Pending,價格是 1.26。
  • 第一次 pay/ 請求返回 HTTP 402,accepts 中有 Base exact 和 Solana exact,金額都是 1200000 atomic USDC。
  • 帶 Base PAYMENT-SIGNATURE 重試後返回 HTTP 200,訂單狀態變為 Finished,pay_way 是 X402。
  • PAYMENT-RESPONSE 解碼後顯示 success=True、network=base,並給出同一個交易雜湊。
  • BaseScan 上交易狀態是 1,轉帳金額是 1200000 atomic USDC,也就是 1.2 USDC。
  • 建立價 1.26 在舊 X402 支付優惠政策期間支付,最終簽名與結算金額為 1.2 USDC。
訂單支付如果沒有 Authorization: Bearer {platform_token},或者訂單不屬於目前帳戶,會在平台權限層失敗;這和直接呼叫 x402.acedata.cloud 的無帳戶 X402 API 不同。

常見錯誤

Base upto 檢查清單

upto 目前只在 Base 上提供(eip155:8453)。由於 upto 簽名會綁定更多 EVM typed data 參數,接入時應特別確認 402 回應中的即時欄位與用戶端簽名完全一致。
如果 Base upto 返回 invalid_upto_evm_payload_invalid_signature,優先檢查:
  1. API 返回的 eip155:8453 + upto 項目裡的 extra.chainId(應為 8453)。
  2. API 返回的 extra.facilitatorAddress。
  3. https://facilitator.acedata.cloud/supported 返回的 Base upto facilitator 地址。
  4. Permit2 domain、spender、USDC 合約和簽名帳戶。
  5. 錢包是否已經對 Base USDC approve Permit2。
upto 的簽名 digest 同時綁定 Permit2 domain、chain ID、spender、收款地址、facilitator 地址和 validAfter。任意一項不一致,Facilitator 都會恢復出錯誤 signer,從而返回 invalid signature。若這些都一致但仍返回 402,下一步檢查 Permit2 allowance;未授權時返回 PERMIT2_ALLOWANCE_REQUIRED。

儲存驗證資訊

一次完整驗證至少儲存:
  • API path 和請求體摘要;
  • 選中的 network 和 scheme;
  • maxAmountRequired;
  • payer 錢包地址;
  • HTTP 最終狀態;
  • 回應中的模型輸出或任務 ID;
  • settlement transaction 連結;
  • Gateway trace ID 或平台使用記錄 ID。
不要儲存私鑰、完整 PAYMENT-SIGNATURE、完整 EIP-712 signature 或助記詞。

結構化支付錯誤

簽名後的 X402 失敗會在 extensions.acedatacloud.paymentError 返回穩定 code、安全插值參數、階段和可重試標誌。優先使用該結構排查,不要解析頂層英文 error,也不要要求使用者提供錢包簽名或鏈上模擬原文。
  • charged: false:驗證在結算前明確拒絕,本次沒有發起扣款。
  • 不含 charged:結果未知或已進入結算階段,先查訂單和鏈上狀態,禁止直接重複支付。
  • settlement_pending:暫勿重複支付,先重新整理訂單或聯絡支援。
  • 未識別 code:按 payment_failed 處理,並保留公開技術代碼供客服檢索。