エージェント決済実行 (x402)

AIエージェントが自律的に支払うことができ、組み込みの支出管理を備えています。x402 HTTP決済プロトコルとMCPツールを使用すると、エージェントは外部サービス、API、または他のエージェントに対して支払い、カストディアルリスクなしで支払うことができます。

ユースケース

以下に適しています:エージェントがAPI呼び出しの支払い、サービスの購入、他のエージェントとの決済、タスク単位の消費制限の強制実行、またはノンカストディアルウォレットの管理が必要な場合。コスト認識型LLMパイプラインとセキュリティ監査スキルとの組み合わせに最適です。

動作方式

x402プロトコル

x402はHTTP 402（支払い必要）を機械ネゴシエーション可能なプロセスに拡張します。サーバーが402を返すと、エージェントの支払いツールは自動的に価格をネゴシエートし、予算をチェックし、トランザクションに署名し、再試行します——人手を介さずに。

支出管理

支払いツール呼び出しのたびにSpendingPolicyを強制実行します:

• タスク単位予算 — 単一のエージェント操作における最大支出額
• セッション単位予算 — セッション全体の累積上限
• ホワイトリスト受取人 — エージェントが支払える住所/サービスを制限
• レート制限 — 分単位/時間単位の最大トランザクション数

ノンカストディアルウォレット

エージェントはERC-4337スマートアカウントを通じて独自のキーを保有します。オーケストレータが委譲前にポリシーを設定します;エージェントは制限範囲内でのみ支出できます。資金プール、カストディアルリスクなし。

MCP統合

決済レイヤーは標準MCPツールを公開し、任意のClaude Codeまたはエージェントフレームワークのセットアップにシームレスに統合できます。

セキュリティに関する注意：パッケージバージョンを必ずロックしてください。このツールは秘密鍵を管理します——ロックされていないnpxインストールはサプライチェーンリスクをもたらします。

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

利用可能なツール（エージェント呼び出し可）

ツール	用途
get_balance	エージェントウォレット残高を確認
send_payment	アドレスまたはENSに支払いを送信
check_spending	残り予算を照会
list_transactions	すべての支払いの監査証跡

注記：支出ポリシーはエージェント自身ではなく、オーケストレータがエージェントに委譲する前に設定します。これはエージェントが自動的に支出制限を引き上げるのを防ぎます。オーケストレータレイヤーまたはタスク前フックでset_policyを通じてポリシーを設定します。エージェント呼び出し可能ツールにしないでください。

例

MCPクライアントにおける予算強制実行

agentpay MCPサーバーを呼び出すオーケストレータを構築するとき、有料ツール呼び出しをディスパッチする前に予算を強制実行します。

前提条件：MCP設定を追加する前にパッケージをインストール——npxが-yなしだと非対話環境で確認プロンプトを表示し、サーバーがハングアップします: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. Validate credentials before constructing the transport.
  //    A missing key must fail immediately — never let the subprocess start without auth.
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY is not set — refusing to start payment server");
  }

  // Connect to the agentpay MCP server via stdio transport.
  // Whitelist only the env vars the server needs — never forward all of process.env
  // to a third-party subprocess that manages private keys.
  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. Set spending policy before delegating to the agent.
  //    Always verify success — a silent failure means no controls are active.
  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. Use preToolCheck before any paid action
  await preToolCheck(agentpay, 0.01);
}

// Pre-tool hook: fail-closed budget enforcement with four distinct error paths.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Path 1: Reject invalid input (NaN/Infinity bypass the < comparison)
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`Invalid apiCost: ${apiCost} — action blocked`);
  }

  // Path 2: Transport/connectivity failure
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Payment service unreachable — action blocked: ${err}`);
  }

  // Path 3: Tool returned an error (e.g., auth failure, wallet not initialised)
  if (result.isError) {
    throw new Error(
      `check_spending failed — action blocked: ${JSON.stringify(result.content)}`
    );
  }

  // Path 4: Parse and validate the response shape
  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}`
    );
  }

  // Path 5: Budget exceeded
  if (remaining < apiCost) {
    throw new Error(
      `Budget exceeded: need $${apiCost} but only $${remaining} remaining`
    );
  }
}

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

ベストプラクティス

• 委譲前に予算を設定：サブエージェント生成時、オーケストレータレイヤー経由でSpendingPolicyを附加します。エージェントに無制限支出権限を与えないでください。
• 依存関係をロック：MCPロック内で常に正確なバージョンを指定します（例:agentwallet-sdk@6.0.0）。本番環境へのデプロイ前にパッケージ整合性を検証します。
• 監査証跡：タスク後フック内でlist_transactionsを使用して、支出内容と理由をログに記録します。
• フェイルクローズ：支払いツールに到達できない場合は有料操作をブロック——無メータリングアクセスへのフォールバックはしないでください。
• セキュリティ監査と組み合わせる：支払いツールは高権限操作です。シェルアクセスと同じ監査基準を適用します。
• テストネットで先にテスト：開発時はBase Sepoliaを使用します;本番環境ではBase mainnetに切り替えます。

本番環境リファレンス

• npm：agentwallet-sdk
• NVIDIA NeMo Agent Toolkitへのマージ：PR #17 — NVIDIAエージェント例のx402決済ツール
• プロトコル仕様：x402.org