agent-payment-x402

Name: agent-payment-x402
Author: affaan-m

Agent 支付執行功能 (x402)

讓 AI Agent 能夠在內建支出控制的規範下執行政策受控的支付操作。採用 x402 HTTP 支付協定與 MCP 工具，Agent 無需承擔託管風險，即可付費使用外部服務、API 或向其他 Agent 結帳。

何時使用

適用情境：當您的 Agent 需要付費呼叫 API、購買服務、與其他 Agent 進行結帳、強制執行單次任務支出上限，或管理非託管錢包時使用。非常適合搭配 cost-aware-llm-pipeline 與 security-review 等 Skill 一起使用。

決策樹

根據您的 Agent 是要購買付費 API 的存取權，還是要向其他 Agent 收費，來選擇對應的整合路徑：

需求	建議整合路徑
Agent 要付費存取 Base 或其他 agentwallet 支援鏈上的 402 閘道 API	搭配嚴格的支出政策，將 `agentwallet-sdk` 作為 MCP 支付伺服器使用
Agent 要付費存取 X Layer 上的 402 閘道 API	使用來自 `okx/onchainos-skills` 的 OKX Agent Payments Protocol；`okx-x402-payment` 為已淘汰的舊版別名
TypeScript API 要向 Agent 收費	參閱 Express、Hono、Fastify 或 Next.js 的 OKX Payments TypeScript 賣方 SDK 文件
Go API 要向 Agent 收費	參閱 Gin、Echo 或 `net/http` 的 OKX Payments Go 賣方 SDK 文件
Rust API 要向 Agent 收費	參閱 Axum 的 OKX Payments Rust 賣方 SDK 文件
Java API 要向 Agent 收費	參閱 Spring Boot 2/3、Java EE 或 Jakarta 的 OKX Payments Java 賣方 SDK 文件
Python API 要向 Agent 收費	實作前請先確認最新的 OKX Payments 儲存庫；目前可能尚未提供 Python 賣方指南

支援的網路

agentwallet-sdk：上正式環境前，請參閱套件文件以確認目前的網路支援範圍。Base Sepolia 是最安全的開發預設值；Base 主網是原始 Skill 採用的正式環境路徑。
OKX Payments / X Layer：目前的賣方文件主要針對 X Layer (eip155:196) 與 USDT0 結帳。由於支付套件與中介器（facilitator）行為變化快速，在生成正式環境程式碼前請先抓取最新的 SDK 文件。

運作原理

x402 協定

x402 將 HTTP 402 (Payment Required) 延伸為機器可自動協商的流程。當伺服器回傳 402 時，Agent 的支付工具會進行議價、檢查預算、簽署交易，且僅會在協調器（orchestrator）設定的政策與確認邊界內重試。

支出控制

每次呼叫支付工具都會強制執行 SpendingPolicy：

單次任務預算 — 單一 Agent 動作的最大支出金額
單次階段預算 — 整個 session 的累計上限
白名單收款方 — 限制 Agent 僅能支付給特定的位址/服務
速率限制 — 每分鐘/每小時的最大交易筆數

非託管錢包

Agent 透過 ERC-4337 智慧帳戶自行持有金鑰。協調器在委派任務前先設定好政策；Agent 只能在授權邊界內進行支出。無需資金池，完全零託管風險。

MCP 整合

支付層暴露標準的 MCP 工具，可無縫接軌至任何 Claude Code 或 Agent 架構設定中。

資安提醒：請務必鎖定套件版本。此工具會管理私鑰 — 使用未鎖定版本的 npx 安裝可能帶來供應鏈風險。

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

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["agentwallet-sdk@6.0.0"]
    }
  }
}

可用工具（Agent 可呼叫）

工具	用途
`get_balance`	查詢 Agent 錢包餘額
`send_payment`	發送支付至指定位址或 ENS
`check_spending`	查詢剩餘預算額度
`list_transactions`	稽核所有支付的歷史紀錄

注意：支出政策是由**協調器 (orchestrator)**在委派任務給 Agent 之前設定的，而不是由 Agent 本身設定。這能防止 Agent 自行提高支出額度。請透過編排層中的 set_policy 或任務前置 Hook 設定政策，絕不要將其暴露為 Agent 可呼叫的工具。

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

若要使用 X Layer 的 x402、多方支付 (MPP)、階段支付、扣款及 A2A (Agent-to-Agent) 扣款流程，請採用此路徑。

針對買方端的 Agent 流程：

安裝或參考最新的 okx/onchainos-skills 儲存庫。
使用 skills/okx-agent-payments-protocol/SKILL.md 作為分派器 (dispatcher)。
將 skills/okx-x402-payment/SKILL.md 視為已棄用的相容性別名，而非標準 Skill。
在執行錢包狀態檢查或支付動作前，必須要求使用者明確確認。切勿將支付執行隱藏在通用的工具呼叫之後。

針對賣方端的 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 設定之前請先安裝套件 — 在非互動式環境中，未使用 -y 參數的 npx 會提示要求確認，導致伺服器停擺：npm install -g agentwallet-sdk@6.0.0

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

async function main() {
  // 1. 在建立傳輸通道 (transport) 之前驗證憑證。
  //    若缺乏私鑰必須立即拋出錯誤 — 絕不允許子程式在未授權的情況下啟動。
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY is not set — refusing to start payment server");
  }

  // 透過 stdio transport 連線至 agentpay MCP 伺服器。
  // 僅將伺服器所需的環境變數列入白名單 — 絕不要將完整的 process.env
  // 轉發給管理私鑰的第三方子程式。
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["agentwallet-sdk@6.0.0"],
    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. 在委派任務給 Agent 之前先設定支出政策。
  //    務必驗證是否成功 — 靜默失敗意味著沒有任何控制機制生效。
  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(
      `Failed to set spending policy — do not delegate: ${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. 在執行任何付費動作前呼叫 preToolCheck
  await preToolCheck(agentpay, 0.01);
}

// 工具前置 Hook：預設關閉（fail-closed）的預算管制，包含四種不同的錯誤處理路徑。
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // 路徑 1：拒絕無效輸入（NaN/Infinity 會繞過 < 比較演算）
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`Invalid apiCost: ${apiCost} — action blocked`);
  }

  // 路徑 2：傳輸通道/連線失敗
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Payment service unreachable — action blocked: ${err}`);
  }

  // 路徑 3：工具回傳錯誤（例如：驗證失敗、錢包未初始化）
  if (result.isError) {
    throw new Error(
      `check_spending failed — action blocked: ${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("missing or non-finite 'remaining' field");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending returned unexpected format — action blocked: ${err}`
    );
  }

  // 路徑 5：超出預算
  if (remaining < apiCost) {
    throw new Error(
      `Budget exceeded: need $${apiCost} but only $${remaining} remaining`
    );
  }
}

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

最佳實踐

委派前先設定預算：產生子 Agent (sub-agent) 時，請透過編排層附帶 SpendingPolicy。切勿給予 Agent 無上限的支出權限。
鎖定相依套件版本：在 MCP 設定中務必指定精確版本（例如 agentwallet-sdk@6.0.0）。在部署至正式環境前，先驗證套件完整性。
稽核紀錄：在任務後置 Hook 中使用 list_transactions 來記錄支出金額與原因。
失敗即封鎖 (Fail closed)：如果支付工具無法連線，應封鎖該付費動作，而不是退回至不受控的存取狀態。
搭配 security-review 使用：支付工具屬於高權限工具。應比照 Shell 存取權限進行相同等級的安全性審查。
先在測試網進行測試：開發階段使用 Base Sepolia；上正式環境再切換至 Base 主網。

正式環境參考資源

npm：agentwallet-sdk
已合併至 NVIDIA NeMo Agent Toolkit：PR #17 — 適用於 NVIDIA Agent 範例的 x402 支付工具
協定規格：x402.org
OKX Payments SDK：okx/payments — 適用於 X Layer x402 的 TypeScript、Go、Rust 與 Java 賣方整合
OKX Agent Payments Protocol skill：okx/onchainos-skills
OKX Payments 總覽：web3.okx.com/onchainos/dev-docs/payments/overview

您可能也喜歡

homelab-network-readiness

240Kmcp-integrations

Readiness checklist for homelab VLAN segmentation, local DNS filtering, and WireGuard-style remote access before changing router, firewall, DHCP, or VPN configuration.

affaan-m

獲取

agent-tool-builder

47Kmcp-integrations

Tools are how AI agents interact with the world. A well-designed

sickn33

獲取

mcp-developer

11Kmcp-integrations

在建立、除錯或擴充 MCP 伺服器或客戶端，以連接 AI 系統與外部工具和資料來源時使用。呼叫以實作工具處理器、設定資源提供者、建立 stdio/HTTP/SSE 傳輸層、使用 Zod 或 Pydantic 驗證架構、除錯協定合規問題，或使用 TypeScript 或 Python SDK 搭建完整的 MCP 伺服器/客戶端專案。

jeffallan

獲取

繼續探索

瀏覽 mcp-integrations 熱門 Skills 最近更新