x402 付款測試

x402 收費資源先返回 402 Payment Required 和付款要求。Agent Payments 會在策略、預算、審批和簽名器約束內完成付款，再攜帶付款簽名重新傳送同一份 HTTP 請求。購買流程支援 HTTPS GET、POST、PUT、PATCH 和 DELETE 請求。

開始前請先完成快速開始，並確認執行時 MCP 與簽名伴隨服務正常。建議首次使用沙盒錢包和小額測試資產，並讓付款進入人工審批。

本教程使用 Base Sepolia USDC。如果其它收費服務要求不同網路，請確認付款要求與支援範圍所列網路和 USDC 一致，再從需要人工審批的小額付款開始。

1. 檢查付款要求

下面的面板會按照你填寫的資源地址、HTTP 請求方法、查詢參數和請求體讀取服務實際返回的 402 挑戰。網路、資產、金額、收款地址和付款方案都以回應為準，面板不預設 Base Sepolia、USDC 或 exact。它不會在瀏覽器中持有私鑰、建立 Intent 或付款。

檢查器能夠讀取的挑戰範圍有意寬於 Agent Payments 的實際購買範圍。成功顯示挑戰不代表可以購買。付款要求仍必須使用受支援的 x402 版本、付款方案、HTTPS 請求方法、網路和 USDC。批准付款前先執行預檢，確認 StableOps 能否繼續。

跨域服務還需允許文件站來源、所選請求方法和 Content-Type，並透過 Access-Control-Expose-Headers 公開 PAYMENT-REQUIRED 或 X-PAYMENT-REQUIRED，否則瀏覽器無法讀取完整挑戰。

2. 讓 Agent 預檢資源

如果已有收費資源，請準備包含路徑和查詢參數的完整 HTTPS 地址。沒有目標時，可以讓 Agent 先發現候選服務。把下面的指令交給已設定執行時 MCP 的 Agent：

請使用 StableOps Agent Payments MCP 準備一筆沙盒 x402 付款。

- 目標網址：<填寫完整 HTTPS 地址，沒有目標時先發現候選服務並讓我選擇>
- 請求方法：POST
- 內容型別：application/json
- 準確請求體：{"query":"stablecoins","limit":10}
- 先檢查執行身份、支援網路、預算和簽名伴隨服務狀態
- 對最終選定的準確網址執行付款預檢
- 展示網址、網路、資產、金額、收款地址、策略結論、警告和預計預算
- 儲存預檢返回的 preview_token
- 不要建立付款 Intent，等待我確認

Agent 會呼叫 stableops_preview_x402_purchase。預檢是隻讀操作，不建立付款 Intent，也不佔用預算。對於非 GET 請求，不透明的 preview_token 還會繫結請求方法、準確請求體和內容型別。請求體只保留在 MCP 程序記憶體中並直接發給資源服務。StableOps 只接收其 SHA-256 摘要和內容型別。繼續前應核對請求方法、準確網址、請求體、網路、資產、金額和收款地址。預檢拒絕或返回內容與預期不符時不要付款。

直接使用 SDK 時寫法相同：

const result = await agent.x402Fetch('https://resource.example.com/search', {
  method: 'POST',
  body: JSON.stringify({ query: 'stablecoins', limit: 10 }),
  contentType: 'application/json',
  idempotencyKey: 'research-task-284:search:v1',
})

請求體可以是字串或準確的 Uint8Array 位元組。Agent Payments 會對這些準確位元組計算摘要並原樣重發，不會代替呼叫方序列化 JavaScript 物件。非 GET 請求可以使用空請求體，此時會繫結空請求體的 SHA-256 摘要。GET 請求不能攜帶請求體或內容型別。

3. 確認併發起付款

確認預檢結果後，向同一個 Agent 傳送：

確認購買剛才預檢的準確網址。
使用剛才的 preview_token，並把 idempotency_key 設為 x402-first-purchase-001。
不得更換請求方法、網址、查詢參數、請求體、內容型別、收款地址或提高金額。
如果需要人工審批，儲存 intent_id 後停止，不要建立另一筆付款。
如果付款成功，返回資源回應和 intent_id。

Agent 會呼叫 stableops_x402_fetch。正式購買會重新傳送原請求以讀取最新付款要求，並再次檢查策略、預算、錢包、風控和預檢約束。簽名後，SDK 會使用同一請求方法和請求體，並加入 PAYMENT-SIGNATURE 後再次傳送。同一筆業務購買的所有重試必須複用相同的 idempotency_key。

對於 POST 等可能產生業務副作用的操作，資源服務必須在執行受保護操作前返回 402。SDK 在發現和重新整理付款挑戰時可能多次傳送該請求。如果賣方介面提供業務冪等欄位，應把穩定值寫入請求體。StableOps 的 idempotency_key 只用於去重付款 Intent，不能代替賣方應用自身的業務冪等機制。

4. 處理人工審批

如果結果為 awaiting_approval，在 StableOps 控制台核對並審批該付款，然後讓 Agent 恢復原付款：

付款 Intent <填寫 intent_id> 已批准。
請恢復原付款，繼續使用原請求方法、準確網址、請求體、內容型別和 preview_token。
不要建立新 Intent，也不要更換 idempotency_key。

Agent 會呼叫 stableops_resume_x402_purchase 恢復原付款。付款被拒絕時不要恢復。

如果 MCP 已重啟，應使用同一請求方法、準確網址、請求體和內容型別重新預檢，再用新的 preview_token 恢復同一個 intent_id。Control API 會在簽發授權前比較請求方法、完整網址雜湊、請求體摘要、內容型別和最新付款要求。Agent 不得用另一筆付款替代等待審批或狀態未知的付款。

5. 核對結果

• paid 表示付費 HTTP 請求已經得到可靠資源回應。
• settled 表示控制面已經確認鏈上結算。
• settlement_unknown 表示結果尚不確定，只能查詢原 intent_id，不能重新付款。

讓 Agent 使用 stableops_get_payment 查詢原付款，並返回資源回應、付款狀態和收據。需要非同步接收審批、結算或異常狀態時，設定簽名 Webhook。