エージェント支払い実行 (x402)

エージェント支払い実行 (x402) は何をしますか？

AIエージェントが組み込みの支出制御機能付きでポリシーに基づいた支払いを行えるようにします。x402 HTTP支払いプロトコルとMCPツールを使用することで、エージェントはカストディアルリスクなしに外部サービス、API、他のエージェントへの支払いを行うことができます。

使用するタイミング

以下の場合に使用します: エージェントがAPIコールの支払い、サービスの購入、他のエージェントとの決済、タスクごとの支出制限の適用、非カストディアルウォレットの管理を行う必要がある場合。cost-aware-llm-pipeline や security-review スキルと自然に組み合わせて使用できます。

決定木

エージェントが有料APIへのアクセスを購入するのか、自身のAPIに対して他のエージェントに課金するのかに基づいて、統合パスを選択します。

ニーズ	推奨パス
エージェントがBaseまたはagentwallet-sdkがサポートする他のチェーン上の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 を適用します:

• タスクごとの予算 — 単一のエージェントアクションに対する最大支出額
• セッションごとの予算 — セッション全体での累積制限
• 許可リストに登録された受取人 — エージェントが支払い可能なアドレス/サービスを制限
• レート制限 — 1分/1時間あたりの最大トランザクション数

非カストディアルウォレット

エージェントはERC-4337スマートアカウントを介して自身の鍵を保持します。オーケストレーターが委任前にポリシーを設定し、エージェントはその範囲内でのみ支出できます。資金のプールはなく、カストディアルリスクもありません。

MCP統合

支払いレイヤーは、任意のClaude Codeまたはエージェントハーネスセットアップに組み込める標準的なMCPツールを公開します。

セキュリティ注意: 常にパッケージバージョンを固定してください。このツールは秘密鍵を管理します — 固定されていない 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);
}

// ツール前フック: 4つの異なるエラーパスを持つ、フェイルクローズドな予算執行。
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 を使用して、何がなぜ使われたかを記録します。
• フェイルクローズド: 支払いツールに到達できない場合は、有料アクションをブロックします — 計測なしのアクセスにフォールバックしないでください。
• セキュリティレビューと組み合わせる: 支払いツールは高権限です。シェルアクセスと同じ注意を払ってください。
• まずテストネットでテストする: 開発には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