【2026 最新】x402 教學：用 Cloudflare 讓 AI Agent 自動付費（API＋MCP）

x402 教學先抓一句話：x402 是把「收費單、錢包簽章、付款驗證與原請求重試」放進 HTTP 往返的開放協定。整合過 x402 的 AI Agent 遇到付費 API 或 MCP tool 時，可以先讀價格與付款條件，再依預算政策決定是否簽章付款；它不是任何 Agent 看到 402 都會自動掏錢的魔法。

2026 年 8 月 10 日，一篇談「把資料賣給 AI Agent」的 X 長文，把 AI Crawl Control、Pay Per Crawl、Monetization Gateway 與 x402 串成一個很吸引人的故事。方向值得研究，但產品狀態不能混在一起：截至 2026 年 8 月 12 日，Cloudflare 的 Monetization Gateway 仍在 waitlist，Pay Per Crawl 是 closed beta；現在可以自己動手跑的，是 Workers／Agents SDK 的 x402 開發工具。

這篇會先建立正確心智模型，再帶你複製 Cloudflare 官方 agents/examples/x402，只在 Base Sepolia 測試網跑完「第一次拿到 402 → 測試錢包簽章 → facilitator 驗證與結算 → 第二次取得 200」的完整往返。你最後會得到一個本機付費 API 範例，也會知道它離 production 還缺哪些預算、金鑰、快取與重試防線。

先說結論：x402 是 HTTP 收費單，不是自動扣款按鈕

🧠 記憶把手：x402 付費資源 ＝ 原 HTTP 請求＋402 收費單＋錢包付款證明＋驗證／結算＋帶證明重試。
伺服器開價，client 依自己的資產、網路與預算政策決定要不要接受；只有付款被驗證後，伺服器才交付內容。

把它想成一台只接受電子簽名的自動販賣機。Agent 第一次按商品鍵時不會立刻拿到飲料，而是收到「價格、收款地址、接受哪條網路與資產」；錢包同意並簽名後，再按一次同一個鍵。facilitator 像驗鈔與入帳服務，確認付款授權可用並完成結算；它不是替買賣雙方保管餘額的銀行帳戶。

這個機制應放在完整的 Agent 控制框架內。若你還不熟悉誰負責工具權限、失敗重試與狀態，可先讀《AI Agent Harness 是什麼》；要看如何把安全閘門接進一條可執行流程，再搭配《動手做 AI Agent Harness》。

為什麼偏偏是 402？先分清 HTTP 狀態碼與 x402 協定

RFC 9110 至今仍把 HTTP 402 Payment Required 保留給未來使用，沒有替它定義錢包、資產或結算格式。x402 是一套另外建立的應用層協定：它借用 402 當挑戰訊號，再定義 client 與 resource server 要如何交換付款要求、付款證明與收據。因此，「回傳 402」和「已收到錢」是兩件完全不同的事。

1. Client 先送原請求：例如 GET /protected-route，還沒有付款證明。
2. Server 回傳 402：PAYMENT-REQUIRED 內含方案、價格、CAIP-2 network、資產與收款地址。
3. Client 選方案並簽章：錢包只在符合 allowlist、單筆上限與人工核准規則時產生授權。
4. Client 重試原請求：這次帶上 PAYMENT-SIGNATURE。server 或 facilitator 驗證，再嘗試結算。
5. Server 交付資源：成功才回 200 與 PAYMENT-RESPONSE 收據；驗證或結算失敗不應交付付費內容。

官方 client-server 規格把 facilitator 設計成可選角色：resource server 可以自行驗證／結算，也可以委託 facilitator。這種拆法很像《Stateless MCP》談的責任邊界——狀態與能力不一定留在同一條連線，但每一方仍要知道自己保存、驗證與重試什麼。

Cloudflare x402 教學前，先把 4 個產品名字拆開

原始討論最容易誤導新手的地方，是把「crawler 控制」、「按次爬取收費」、「開發者 payment primitives」與「未來的統一收費閘道」當成同一套已上線產品。它們目前的狀態與付款 rail 都不同：

• Agents SDK／Workers 的 Agentic Payments：官方文件已有 x402 與 MPP 的開發路徑；本文會用其中的 x402 v2 範例。
• AI Crawl Control：目前是 GA，可查看、允許或封鎖 AI crawler。付費方案可把封鎖回應改成自訂 402 聯絡／授權訊息，但那段訊息本身不會收款。
• Pay Per Crawl：目前仍是 closed beta，採 Web Bot Auth、Stripe 與 Cloudflare 自有的 crawler-price 等 headers；它不是 x402。網站可設 allow／charge／block，文件公開的最低價格是每次成功 crawl 0.001 美元。
• Monetization Gateway：2026 年 7 月 1 日宣布並開放 waitlist。頁面、dataset、API、MCP、edge 驗證、規則 API 與 Terraform 都是官方描述的預定能力；官方尚未公布正式價格、資產／網路矩陣或 GA 日期。

另一個必須拆開的概念是付費 access、付費 crawl、付費 tool call、後續內容使用與授權。x402 只證明某次資源請求依規則付款；它不會知道模型後來是否引用內容，也不會自動授予重製、訓練或再散布權。若產品涉及第三方資料，授權與隱私仍要另外處理。

動手做 x402 教學：在 Base Sepolia 跑官方 Agents 範例

以下鎖定 Cloudflare 官方 agents/examples/x402 的 current main 範例。它用 Hono 保護 /protected-route，定價 0.10 美元，network 是 Base Sepolia 的 CAIP-2 識別 eip155:84532。套件版本變動很快，請記錄 clone 的 commit 並保留安裝後產生的 lockfile，不要把不同年代的 blog snippet 混貼。

本文在 2026 年 8 月 12 日以 commit b9343a0dadb5 實測：npm install、產生 Wrangler types、TypeScript --noEmit 與 Vite production build 都通過；本機首頁回 200，未附付款的 protected route 回 402。這次 smoke test 刻意沒有放 buyer private key、沒有按 Agent RPC，也沒有執行 funded transaction，所以不把它包裝成真實結算實測。當次安裝解析到 agents@0.20.1、@x402/*@2.22.0；日後版本可能不同。

準備 Node.js、npm、兩個只供測試的 EVM 地址：SERVER_ADDRESS 是收款地址，CLIENT_TEST_PK 是付款測試錢包的 private key。後者只放少量 Base Sepolia 測試資產，絕對不要使用主錢包、不要貼到前端程式、Git 或 log。測試資產可從 README 指向的 Circle Faucet 取得。

git clone --depth 1 https://github.com/cloudflare/agents.git
cd agents/examples/x402
cp .env.example .env
npm install

打開 .env，只填測試資料：

SERVER_ADDRESS=0x你的_Base_Sepolia_收款地址
CLIENT_TEST_PK=0x只供測試的付款錢包私鑰

啟動本機服務：

npm start

先用普通 curl 看清楚 paywall：它沒有錢包，所以預期只會收到 402，不會移動任何資產。

curl -i http://localhost:5173/protected-route

接著在官方範例頁按 Fetch & Pay。只有測試錢包已有相符資產時，@x402/fetch 才能代替普通 fetch 讀取付款要求、簽章並重試；完成後畫面會顯示受保護 route 回傳的 JSON。若只看到 402，依序檢查錢包餘額、network、收款地址與 facilitator 支援，不要為了「跑通」改用真實資金。

伺服器究竟改了什麼？一段 middleware 就能替 route 開價

官方範例的核心不是 Agent 介面，而是 paymentMiddleware()。以下保留真正影響交易語意的欄位：

import { paymentMiddleware, x402ResourceServer } from "@x402/hono";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { registerExactEvmScheme } from "@x402/evm/exact/server";

const facilitator = new HTTPFacilitatorClient({
  url: "https://x402.org/facilitator"
});
const resourceServer = new x402ResourceServer(facilitator);
registerExactEvmScheme(resourceServer);

app.use(paymentMiddleware({
  "GET /protected-route": {
    accepts: [{
      scheme: "exact",
      price: "$0.10",
      network: "eip155:84532",
      payTo: process.env.SERVER_ADDRESS
    }],
    description: "Access to premium content",
    mimeType: "application/json"
  }
}, resourceServer));

exact 表示固定收費，eip155:84532 明確把簽章與結算鎖在 Base Sepolia，payTo 則是 seller 地址。client 端用 @x402/core 建立 client、註冊 EVM signer，再用 wrapFetchWithPayment() 包住 fetch。普通瀏覽器不會憑空擁有 signer，因此不會因為打開付費 URL 就自動扣款。

把一次請求逐格追完：402、簽章、settle、200

假設 Agent 想拿 /protected-route 的 JSON。以下 header 只保留概念欄位，不是可直接重播的真實簽章：

# 1. 第一次請求
GET /protected-route

# 2. Server 挑戰
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 payment requirements>

# 3. Client 符合政策後，重試同一個 request
GET /protected-route
PAYMENT-SIGNATURE: <signed authorization>

# 4. 驗證與結算成功，才交付資源
HTTP/1.1 200 OK
PAYMENT-RESPONSE: <base64 settlement receipt>

這裡最容易漏的是失敗路徑。錢包可以拒絕價格；資產或 network 可能不相容；facilitator 可能無法驗證或結算。@x402/fetch 會處理一次付費重試，但不等於你的業務操作已具備 exactly-once。若付費後的 route 會建立訂單、寄信或寫資料庫，仍要用 payment identifier 與持久化 idempotency key 綁定 request payload。這和《Code-Implemented Tool Calls》裡「工具結果可重播，不等於外部副作用只發生一次」是同一類工程問題。

HTTP API 與 MCP 怎麼選？付款流程相同，包裝位置不同

若資源本來就是 REST endpoint、檔案或資料查詢，直接用 @x402/hono／@x402/fetch 最直覺。若能力是「查庫存、算模型、讀專有 archive」這類 Agent tool，Cloudflare Agents SDK 可用 withX402() 包住 MCP server，再註冊 paidTool()：

const paidServer = withX402(server, {
  network: "eip155:84532",
  recipient: "0xYOUR_TEST_RECEIVER",
  facilitator: { url: "https://x402.org/facilitator" }
});

paidServer.paidTool(
  "square",
  "Squares a number",
  0.01,
  { number: z.number() },
  {},
  async ({ number }) => ({
    content: [{ type: "text", text: String(number ** 2) }]
  })
);

MCP transport 會把付款要求、證明與 receipt 放在 JSON-RPC 的 _meta，而不是 HTTP 的三個 PAYMENT-* headers；經濟流程仍是 challenge、approve、verify／settle、execute。若你在比較 MCP 和一般命令列工具的成本，可讀《MCP vs CLI Token 實測》，但不要把 token 成本和鏈上付款金額混成一個指標。

從測試網到 production：先過 7 道安全閘門

1. 換掉 public test facilitator：https://x402.org/facilitator 是開發／測試網用途。正式上線要另選或自架支援 mainnet 的 facilitator，逐項確認驗證方式、API key、費用、rate limit 與失敗語意；不能只把 network 從 Sepolia 改成 Base。
2. 把 private key 留在 secret manager：buyer signer 不進 browser、原始碼、Git、analytics 或 log。完整做法可搭配《AI Agent Secret 安全教學》。
3. 預算要有兩層：單筆 maxPaymentValue 只擋一筆，不是每日總額。另建 persisted daily／monthly spend ledger、seller／route allowlist，超額 fail closed。
4. 高風險付款保留人工確認：顯示 seller、資產、network、原子單位與換算金額；不要只顯示一個「同意」按鈕。
5. 寫入操作做 idempotency：付款證明、payment identifier 與業務 payload 綁定；相同 ID 配不同 payload 必須拒絕。
6. 付費回應不要只按 URL 快取：在設計好 cache key 前，402 與個人化付費內容先用 Cache-Control: private, no-store。否則上一位買家的 200 可能被下一位免費拿走。
7. 保留 auth 與授權：付款證明不是使用者身分。需要帳號、角色、地區資格或稽核責任時，OAuth／API auth 與 entitlement 仍然存在。

x402 官網所說的「zero protocol fees」只代表協定本身不抽成，不代表總成本為零。facilitator、鏈上 network、Worker、KYT／合規與失敗重試都可能產生成本；push payment 執行後也不能像信用卡那樣直接 reverse，退款通常是 seller 另送一筆新交易。

x402 教學 FAQ

任何 AI Agent 收到 402 都會自動付款嗎？

不會。Agent 必須整合相容 client、有可用錢包與資產，而且價格、seller、network 都通過預算政策；否則它可以拒絕或把決定交給人。

HTTP 402 已經是正式的網路付款標準嗎？

不是。RFC 9110 仍把 402 保留給未來使用。x402 是在其上定義付款資料與流程的開放協定，不代表所有網站或 HTTP client 都相容。

x402 付款完全沒有手續費嗎？

不能這樣說。協定本身不收 protocol fee，但 facilitator、network gas、平台運算、換匯與營運仍可能收費；應以實際 network 與服務商價目表估算。

Cloudflare Pay Per Crawl 就是 x402 嗎？

不是。Pay Per Crawl 目前是 closed beta，使用 Web Bot Auth、Stripe 與 Cloudflare 自有 crawler headers。兩者都可能出現 402，但協定、身分與結算方法不同。

現在可以直接開 Cloudflare Monetization Gateway 嗎？

還不能當成公開產品使用。截至 2026 年 8 月 12 日，官方公告引導加入 early-access waitlist；統一規則、edge 驗證、API 與 Terraform 都仍是預定能力。

內容每被 AI 使用一次，作者就會收到一次錢嗎？

不會自動發生。x402 計的是付費 endpoint 或 tool call，Pay Per Crawl 計的是成功 crawl；它們都不證明模型後來實際引用、訓練或再散布內容，也不取代授權條款。

可以拿真實主錢包照著本文測嗎？

不要。本文只使用 Base Sepolia 與 disposable test wallet。主錢包私鑰不應出現在 .env 教學專案、瀏覽器或任何可記錄的環境。

從測試網改成 mainnet，只要換 network 名稱嗎？

遠遠不夠。還要確認 production facilitator、資產合約與 decimals、認證、gas、費率、KYT、rate limit、settlement failure、idempotency、快取與總預算。Cloudflare 現行片段與 x402 Foundation 對 public facilitator 的用途描述並不完全一致，因此更不能盲改。

給新手的七個重點

1. x402 是 challenge、簽章、驗證／結算與重試的協定，不是 402 狀態碼本身。
2. 只有已整合錢包與政策的 Agent 才可能自動付款，而且它永遠可以拒絕。
3. Agents SDK 的 x402 primitive 現在可實作；Monetization Gateway 仍在 waitlist。
4. Pay Per Crawl 是另一套 closed-beta 收費流程，不是 x402。
5. 先在 eip155:84532 跑完 402 → payment proof → 200，再談 production。
6. 單筆上限不等於總預算；金鑰、allowlist、人工確認、idempotency 與快取都要另做。
7. 付費 access 不等於內容被引用，更不等於自動取得使用與再散布授權。