跳轉到主要內容
X402 是一個由 Coinbase 提出的「按 HTTP 402 計費」的鏈上支付協議:服務端在沒有 token 的請求上回傳 402 Payment Required,附帶 accepts: [...] 欄位列出可接受的鏈 / 資產 / 價格;客戶端在本地簽好一筆授權(EVM 上是 Permit2 / EIP-712,Solana 上是 SPL token transfer 授權),把 base64 後的 envelope 放進 PAYMENT-SIGNATURE 標頭重發。服務端驗證後真正去鏈上結算,再回傳業務結果。
Ace Data Cloud 的 X402 客戶端直接呼叫目標 API,並以該請求即時回傳的 402 Payment Required 和 accepts 作為價格與簽名依據。Facilitator 的支付能力可在 /.well-known/x402 驗證。
@acedatacloud/sdk 和 acedatacloud 都暴露了一個 paymentHandler 鉤子:當 SDK 自己發出的請求收到 402 時,呼叫你注入的 handler 取得 PAYMENT-SIGNATURE 標頭,再重發原請求。把 @acedatacloud/x402-client / acedatacloud-x402 搭配 SDK,整個流程對業務程式碼完全透明——你只用 client.openai.chat.completions.create(...),看起來和 token 模式一模一樣,但底層是按呼叫付費、不需要事先儲值。 本文:
  • 真實串了一遍 TS 端的「無 token + X402 handler 注入」鏈路(T12 驗證)
  • 列了 EVM / Solana 兩套簽名鏈路的差異
  • 給出 viem 私鑰模式、瀏覽器錢包模式、Python EVMAccountSigner 模式三種適配
  • 把 preferScheme / prefer_scheme 這個容易踩坑的欄位說清楚

一、協議總覽(必看)

一次成功的 X402 呼叫涉及 3 個 HTTP RTT:
X402 envelope 是一段 JSON,被 base64 之後塞在 PAYMENT-SIGNATURE 標頭。結構(節選):
envelope 頂層是 x402Version: 2,並用 accepted 物件宣告本次選擇的 scheme 和 network(CAIP-2 識別碼)。 preferScheme / prefer_scheme 用來在服務端同時提供多種 scheme 時選擇偏好。如果服務端只暴露 exact,這個欄位會被忽略;如果設了 upto 但服務端沒暴露,會回退到第一個匹配項。

二、TypeScript:瀏覽器錢包 + 服務端 viem 兩套用法

安裝

實測的版本號:

createX402PaymentHandler 完整簽名

回傳值是一個 (ctx) => Promise&lt;{ headers: Record<string, string> }>,正好對得上 SDK 的 paymentHandler 鉤子簽名。

用法 1:瀏覽器(MetaMask / WalletConnect)

第一次呼叫瀏覽器會跳出兩次簽名提示:第一次是 Permit2 對 USDC 的一次性 approve(金額是 MaxUint256,寫入鏈上);第二次是 X402 envelope 的 EIP-712 簽名(不上鏈,只是給 facilitator 驗證)。後續呼叫只需要第二次簽名,體驗上是「點一次簽名 → 拿結果」。

用法 2:Node 服務端 + viem 私鑰(適合後端 / CLI)

@acedatacloud/x402-client 在 TS 端只接受 EIP-1193 provider——它不直接管理私鑰。在 Node / CLI 情境,標準做法是用 viem 把私鑰包成 WalletClient,再走 @ethereumjs/util 或 viem 內部的 EIP-1193 適配。
如果覺得 viem 的 EIP-1193 適配不夠穩定,也可以走更底層的 signEVMUptoPayment ,自行把 accepts → signed envelope → PAYMENT-SIGNATURE header 這條路串起來,跳過 SDK 掛鉤;不過仍建議優先使用 createX402PaymentHandler,省得自己維護協定升級。

用法 3:Solana

Solana 鏈上目前只暴露 exact scheme,因此 preferScheme 在 Solana 上不起作用。

三、Python:私鑰模式

Python 的 acedatacloud-x402 走的是直接使用私鑰簽名的路徑(沒有 EIP-1193 抽象),更適合伺服器端 / 任務執行器。

安裝

實測版本號:

EVM(Base)

Solana

一次性 approve(僅限 EVM 首次)

EVM Base 上 X402 使用 Permit2,需要錢包對 USDC 向 Permit2 合約進行一次 MaxUint256 的 approve。acedatacloud-x402 內建了 approve_permit2:
這筆交易只需要發送一次,之後所有 X402 EVM 支付都使用這個授權。Solana 不需要。

四、實際執行驗證

測試目標:TS SDK 不傳入 token,注入 X402 handler,能正常建構並發起請求(不消耗真實鏈上 USDC 的輕量驗證)。
輸出:
結果說明:
  • 沒有傳入 apiToken,SDK 建構時不報錯,證明 X402 模式確實是 token 的合法替代方案。
  • createX402PaymentHandler 回傳的是函式(掛鉤),SDK 取得後只會在收到 402 時呼叫。
  • 實際鏈上付費跑通的端對端測試,因為涉及真實 USDC 扣款,沒有放進本教學;可以參考 X402 整合指南 裡的 e2e 範例。
Python 端的 create_x402_payment_handler 也進行了相同驗證 —— 函式回傳值是 callable,注入 payment_handler=... 時 AceDataCloud(...) 建構不報錯。兩邊語意對齊。

五、與「Bearer token 模式」的比較

六、常見陷阱

  1. chat 類必須 preferScheme=upto:用 exact 會讓 facilitator 按 maxAmountRequired(不是實際用量)扣 USDC。
  2. Node 端別傳裸私鑰給 createX402PaymentHandler:TS 套件不接受 { privateKey },必須包成 EIP-1193 provider(推薦 viem WalletClient)。
  3. 首次呼叫是雙簽名:第一次簽 Permit2 approve(上鏈、有 gas),第二次簽 X402 envelope(不上鏈)。後續呼叫只剩第二次。
  4. Solana 沒有 Permit2 概念:直接簽 SPL token transfer 授權,不需要 approve;但目前 Solana 鏈上只支援 exact。
  5. 業務錯誤和支付錯誤區分:402 → handler 失敗拋出 X402SignError(具體類型按鏈不同);後續重發後業務介面的錯誤(401 / 422 / 5xx)仍然按一般 SDK 異常分類。
  6. viem 適配最穩的寫法:evmProvider: walletClient as any 會失去類型檢查但相容性最好;如果想保留類型,用 viem 的 .transport.request 單獨包一層 { request } 物件傳進去。

了解更多