x402 付費 API 的呼叫流程是什麼？

x402 利用 HTTP 402 狀態碼付款：客戶端先請求資源，伺服器回 402 並在 PAYMENT-REQUIRED 標頭說明付款條件；客戶端簽署付款後帶 PAYMENT-SIGNATURE 標頭（v1 為 X-PAYMENT）重送，伺服器驗證結算後回傳資料。

需要準備什麼？

• 支援 x402 的付費 API 端點
• 可簽署付款的錢包與對應網路上的穩定幣
• 能讀寫 HTTP 標頭與處理 Base64 JSON 的程式環境

步驟

1. 送出一般請求

   客戶端像平常一樣呼叫 API，此時還沒有附帶付款資訊。

   GET /api/data HTTP/1.1
   Host: api.example.com

2. 收到 402 與付款要求

   伺服器回應 402 Payment Required，並在 PAYMENT-REQUIRED 標頭放入 Base64 編碼的 PaymentRequired JSON，說明可接受的付款方式、網路、金額與收款地址。

   HTTP/1.1 402 Payment Required
   PAYMENT-REQUIRED: <Base64 編碼的 PaymentRequired JSON>

3. 選擇付款方式並簽署

   客戶端解碼付款要求，從 accepts 中挑選支援的方案，用錢包簽署付款授權，組成 PaymentPayload。

4. 帶付款標頭重送請求

   把 Base64 編碼的 PaymentPayload 放進 PAYMENT-SIGNATURE 標頭重新送出；舊版 v1 使用 X-PAYMENT 標頭。

   GET /api/data HTTP/1.1
   Host: api.example.com
   PAYMENT-SIGNATURE: <Base64 編碼的 PaymentPayload JSON>

5. 伺服器驗證與結算

   伺服器通常交給 facilitator 驗證付款是否符合要求，並把交易送上鏈結算；facilitator 不保管資金。

6. 取得資料與結算結果

   付款成功後伺服器回傳資料，並在 PAYMENT-RESPONSE 標頭附上 Base64 編碼的結算結果（v1 為 X-PAYMENT-RESPONSE）。

   HTTP/1.1 200 OK
   PAYMENT-RESPONSE: <Base64 編碼的 SettlementResponse JSON>

常見錯誤

• v1 與 v2 標頭名稱混用：v2 為 PAYMENT-SIGNATURE／PAYMENT-RESPONSE，v1 為 X-PAYMENT／X-PAYMENT-RESPONSE
• 網路識別碼格式不符：v2 採 CAIP-2 格式（如 eip155:8453），v1 使用 base-sepolia 這類字串
• 標頭內容直接放 JSON 而沒有 Base64 編碼
• 沿用 v1 的 TypeScript 套件名稱（x402-fetch 等）；v2 已改為 @x402/fetch 等 @x402 開頭套件

常見問題

x402 的 facilitator 會保管我的錢嗎？

不會。依 x402 官方文件，facilitator 只負責驗證付款內容是否符合伺服器要求，並將已簽署的付款送上區塊鏈結算，不持有資金也不擔任託管方。

為什麼 x402 適合 AI 代理人使用？

因為付款直接走 HTTP 流程，代理人收到 402 後能自動讀取付款條件、簽署並重送請求，不需要事先註冊帳號或輸入信用卡，適合按次付費的 API 呼叫。

相關名詞

x402 付款協定、API（應用程式介面）、AI 代理人

參考來源

• x402 Docs：HTTP 402
• x402 Docs：Migration Guide V1 to V2
• x402 Docs：Facilitator

查核日期：2026-09-26。API：/api/howto?id=x402-payment-flow