agent-payment-x402

代理程式付款執行 (x402)

讓 AI 代理程式能夠進行政策控管的付款，內建花費控管機制。使用 x402 HTTP 付款協定與 MCP 工具，使代理程式可以為外部服務、API 或其他代理程式付款，而無需承擔託管風險。

何時使用

在以下情況使用：您的代理程式需要為 API 呼叫付費、購買服務、與其他代理程式結算、強制執行每個任務的花費限制，或管理非託管錢包。此技能與 cost-aware-llm-pipeline 和 security-review 技能搭配使用效果最佳。

決策樹

根據您的代理程式是購買付費 API 的存取權限，還是向其他代理程式收費，選擇整合路徑：

需求	建議路徑
代理程式支付 Base 或其他 agentwallet 支援鏈上的 402 閘控 API	使用 agentwallet-sdk 作為 MCP 付款伺服器，並搭配嚴格的花費政策
代理程式支付 X Layer 上的 402 閘控 API	使用 okx/onchainos-skills 中的 OKX Agent Payments Protocol；okx-x402-payment 是已棄用的舊版別名
TypeScript API 向代理程式收費	使用適用於 Express、Hono、Fastify 或 Next.js 的 OKX Payments TypeScript 賣家 SDK 文件
Go API 向代理程式收費	使用適用於 Gin、Echo 或 net/http 的 OKX Payments Go 賣家 SDK 文件
Rust API 向代理程式收費	使用適用於 Axum 的 OKX Payments Rust 賣家 SDK 文件
Java API 向代理程式收費	使用適用於 Spring Boot 2/3、Java EE 或 Jakarta 的 OKX Payments Java 賣家 SDK 文件
Python API 向代理程式收費	實作前請檢查目前的 OKX Payments 儲存庫；可能沒有 Python 賣家指南

支援的網路

• agentwallet-sdk：在正式環境前，請使用套件文件確認目前的網路涵蓋範圍。Base Sepolia 是最安全的開發預設值；Base 主網是原始技能指定的正式環境路徑。
• OKX Payments / X Layer：目前的賣家文件目標為 X Layer (eip155:196) 與 USDT0 結算。在產生正式環境程式碼前，請務必取得最新的 SDK 文件，因為付款套件和促進者行為可能快速變更。

運作方式

x402 協定

x402 將 HTTP 402 (Payment Required) 擴展為機器可協商的流程。當伺服器回傳 402 時，代理程式的付款工具會協商價格、檢查預算、簽署交易，並僅在協調器設定的政策與確認邊界內重試。

花費控管

每個付款工具呼叫都會強制執行 SpendingPolicy：

• 每個任務預算 — 單一代理程式動作的最高花費
• 每個工作階段預算 — 整個工作階段的累積限制
• 允許的收款方白名單 — 限制代理程式可付款的地址/服務
• 速率限制 — 每分鐘/小時的最大交易數

非託管錢包

代理程式透過 ERC-4337 智慧帳戶持有自己的金鑰。協調器在委派前設定政策；代理程式只能在範圍內花費。沒有共用資金，沒有託管風險。

MCP 整合

付款層暴露標準的 MCP 工具，可無縫整合到任何 Claude Code 或代理程式框架設定中。

安全注意事項：務必固定套件版本。此工具管理私鑰 — 未固定的 npx 安裝會引入供應鏈風險。

選項 A：agentwallet-sdk（Base / 多鏈）

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["[email protected]"]
    }
  }
}

可用工具（代理程式可呼叫）

工具	用途
get_balance	檢查代理程式錢包餘額
send_payment	傳送付款到地址或 ENS
check_spending	查詢剩餘預算
list_transactions	所有付款的稽核軌跡

注意：花費政策由協調器在委派給代理程式之前設定 — 而非由代理程式本身設定。這可防止代理程式自行提高花費限制。請在您的協調層或任務前掛鉤中透過 set_policy 設定政策，切勿將其作為代理程式可呼叫的工具。

選項 B：OKX Agent Payments Protocol（X Layer）

使用此路徑進行 X Layer x402、多方付款 (MPP)、工作階段付款、收費和 A2A 收費流程。

對於買方端代理程式流程：

1. 安裝或參考目前的 okx/onchainos-skills 儲存庫。
2. 使用 skills/okx-agent-payments-protocol/SKILL.md 作為分派器。
3. 將 skills/okx-x402-payment/SKILL.md 視為已棄用的相容性別名，而非標準技能。
4. 在錢包狀態檢查或付款動作前，要求明確的使用者確認。請勿將付款執行隱藏在一般工具呼叫之後。

對於賣方端 API 流程，在產生程式碼前請先取得最新的語言特定指南：

執行環境	目前指南
TypeScript	https://raw.githubusercontent.com/okx/payments/main/typescript/SELLER.md
Go	https://raw.githubusercontent.com/okx/payments/main/go/x402/SELLER.md
Rust	https://raw.githubusercontent.com/okx/payments/main/rust/x402/SELLER.md
Java	https://raw.githubusercontent.com/okx/payments/main/java/SELLER.md

請勿在未檢查目前 OKX 儲存庫的情況下複製舊版文件中的範例。目前的 OKX 指南使用 okx-agent-payments-protocol 作為分派器，且 Java 賣家文件現已可用。

範例

在 MCP 用戶端中強制執行預算

在建構呼叫 agentpay MCP 伺服器的協調器時，請在分派付費工具呼叫前強制執行預算。

先決條件：在新增 MCP 設定前先安裝套件 — npx 不加 -y 會在非互動式環境中提示確認，導致伺服器掛起：npm install -g [email protected]

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 1. 在建構傳輸層之前驗證憑證。
  //    遺失金鑰必須立即失敗 — 切勿在沒有驗證的情況下啟動子程序。
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY 未設定 — 拒絕啟動付款伺服器");
  }

  // 透過 stdio 傳輸層連接到 agentpay MCP 伺服器。
  // 僅白名單列出伺服器需要的環境變數 — 切勿將整個 process.env 轉發給管理私鑰的第三方子程序。
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["[email protected]"],
    env: {
      PATH: process.env.PATH ?? "",
      NODE_ENV: process.env.NODE_ENV ?? "production",
      WALLET_PRIVATE_KEY: walletKey,
    },
  });
  const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
  await agentpay.connect(transport);

  // 2. 在委派給代理程式之前設定花費政策。
  //    務必驗證成功 — 靜默失敗表示沒有任何控制機制啟用。
  const policyResult = await agentpay.callTool({
    name: "set_policy",
    arguments: {
      per_task_budget: 0.50,
      per_session_budget: 5.00,
      allowlisted_recipients: ["api.example.com"],
    },
  });
  if (policyResult.isError) {
    throw new Error(
      `設定花費政策失敗 — 請勿委派：${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. 在任何付費動作前使用 preToolCheck
  await preToolCheck(agentpay, 0.01);
}

// 預先工具掛鉤：具有四種不同錯誤路徑的失敗關閉預算強制執行。
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // 路徑 1：拒絕無效輸入（NaN/Infinity 會繞過 < 比較）
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`無效的 apiCost：${apiCost} — 動作已封鎖`);
  }

  // 路徑 2：傳輸層/連線失敗
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`付款服務無法連線 — 動作已封鎖：${err}`);
  }

  // 路徑 3：工具回傳錯誤（例如，驗證失敗、錢包未初始化）
  if (result.isError) {
    throw new Error(
      `check_spending 失敗 — 動作已封鎖：${JSON.stringify(result.content)}`
    );
  }

  // 路徑 4：解析並驗證回應格式
  let remaining: number;
  try {
    const parsed = JSON.parse(
      (result.content as Array<{ text: string }>)[0].text
    );
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("遺失或非有限數值的 'remaining' 欄位");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending 回傳了意外的格式 — 動作已封鎖：${err}`
    );
  }

  // 路徑 5：超出預算
  if (remaining < apiCost) {
    throw new Error(
      `超出預算：需要 $${apiCost}，但僅剩 $${remaining}`
    );
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

最佳實務

• 在委派前設定預算：在產生子代理程式時，透過您的協調層附加 SpendingPolicy。切勿讓代理程式擁有無限花費權限。
• 固定您的相依性：在 MCP 設定中始終指定確切版本（例如 [email protected]）。在部署到正式環境前，驗證套件的完整性。
• 稽核軌跡：在任務後掛鉤中使用 list_transactions 來記錄花費了什麼以及原因。
• 失敗關閉：如果付款工具無法連線，請封鎖付費動作 — 不要退回到未計量的存取。
• 與 security-review 搭配使用：付款工具是高權限的。應採用與 shell 存取相同的審查標準。
• 先在測試網上測試：使用 Base Sepolia 進行開發；正式環境再切換到 Base 主網。

正式環境參考

• npm：agentwallet-sdk
• 已合併至 NVIDIA NeMo Agent Toolkit：PR #17 — NVIDIA 代理程式範例的 x402 付款工具
• 協定規範：x402.org
• OKX Payments SDK：okx/payments — 適用於 X Layer x402 的 TypeScript、Go、Rust 和 Java 賣家整合
• OKX Agent Payments Protocol 技能：okx/onchainos-skills
• OKX Payments 總覽：web3.okx.com/onchainos/dev-docs/payments/overview