跳轉到主要內容
x402 是基於 HTTP 402 Payment Required 狀態碼的支付協議。它實現了機器對機器的 API 微支付,無需手動計費、信用卡或訂閱管理。使用 USDC 按需付費,即時獲得 API 訪問許可權。

工作原理

詳細流程

  1. 客戶端傳送請求到 ChainStream API,沒有 API Key 或 Key 已過期。
  2. 閘道器返回 HTTP 402,訊息指向 /x402/purchase
  3. 客戶端呼叫 GET /x402/purchase?plan=<plan>(不帶支付頭)。伺服器返回 HTTP 402 及 x402 支付要求: 解碼後的 JSON 遵循 x402 v2 協議:
  4. 客戶端使用 @x402 SDK 簽署 USDC 轉賬,並攜帶支付證明重試 GET /x402/purchase?plan=<plan>
  5. 伺服器驗證並結算支付,返回訂閱詳情:
    客戶端儲存 apiKey 用於後續所有 API 呼叫。

CLI 整合

ChainStream CLI 透過 callWithAutoPayment 自動處理 x402 支付。當任何命令遇到 402 時,CLI 會引導你完成套餐選擇和支付。

自動流程

當 CLI 遇到 402 響應時,會:
  1. /x402/pricing 獲取可用套餐並顯示選擇表格
  2. 提示你選擇套餐
  3. 詢問支付方式:x402(Base/Solana USDC)或 MPP(Tempo USDC.e)
  4. 如果選 x402:透過 @x402/fetch 簽名併傳送支付,將返回的 API Key 儲存到配置
  5. 如果選 MPP:列印 tempo request 命令供手動購買
  6. 使用新 API Key 重試原始命令
如果你只有 API Key(沒有錢包),CLI 會跳過 x402 並列印 MPP 購買指引。

錢包設定

CLI 需要一個有餘額的錢包來進行 x402 支付:

手動整合

對於自定義整合,可以使用 @x402 包族實現 x402 流程。

依賴

使用 @x402/fetch(推薦)

最簡單的整合方式 — 用 x402 支援封裝標準 fetch

手動流程(高階)

完全控制支付流程:

支援的支付鏈

零 Gas 費

ChainStream 運營自有的 x402 facilitator,代替 Agent 提交鏈上支付交易。這意味著:
  • 無需 Gas 費 — facilitator 代付所有 gas 費用(Base ETH / Solana SOL)
  • Agent 錢包只需持有 USDC — 無需持有原生代幣支付 gas
  • Agent 簽署 USDC 轉賬授權;facilitator 負責廣播交易並支付執行費用
這消除了 AI Agent 最大的摩擦點:在多條鏈上獲取和管理原生 gas 代幣。

安全注意事項

  • 支付上限:使用 @x402/fetch 時始終設定 maxAmount 以防止意外扣費。
  • 驗證:facilitator 在結算前會在鏈上驗證簽名支付。無效簽名會被拒絕。
  • 冪等性:如果支付已結算但響應失敗(網路錯誤),可以重新提交相同的 Payment-Signature。支付只會被消費一次。
  • 合規:付款方地址在結算前會進行合規篩查。受制裁地址會被拒絕。