agent-payment-x402 skill

エージェント決済実行（x402）

ポリシーゲートによる決済と組み込みの支出コントロールで AI エージェントを有効化します。x402 HTTP 決済プロトコルと MCP ツールを使用して、カストディアルリスクなしに外部サービス、API、または他のエージェントへの支払いを行えます。

使用タイミング

使用する場合：エージェントが API 呼び出しへの支払い、サービスの購入、別のエージェントとの決済、タスクごとの支出制限の強制、またはノンカストディアルウォレットの管理を必要とする場合。cost-aware-llm-pipeline および security-review スキルと自然に組み合わせられます。

決定ツリー

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

対応ネットワーク

• agentwallet-sdk: 本番使用前に現在のネットワークカバレッジをパッケージドキュメントで確認。Base Sepolia が最も安全な開発デフォルト；Base メインネットがオリジナルスキルで説明されている本番パス。
• OKX Payments / X Layer: 現在のセラードキュメントは X Layer（eip155:196）と USDT0 決済を対象。決済パッケージとファシリテーターの動作が迅速に変わる可能性があるため、本番コードを生成する前に現在の SDK ドキュメントを取得すること。
• アップストリーム x402 パッケージ: 設計上マルチネットワーク — 1 つのルートで Base と Solana を同時に提示し、買い手に選ばせることができる。パッケージのデフォルトは x402.org ファシリテーターで、テストネット専用（Base Sepolia eip155:84532、Solana デブネット solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1、加えて Stellar、Aptos、Hedera、XRPL の各テストネット）であり、メインネットルート向けではない。メインネット（Solana は solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp）では、自己ファシリテートするか、自前のファシリテーターを運用するか、アップストリームのファシリテーターリストからホスト型を選ぶ — オプション C のファシリテーター比較を参照。本番前にここにハードコードするのではなく、ファシリテーターの /supported エンドポイントでライブカバレッジを確認すること。

仕組み

x402 プロトコル

x402 は HTTP 402（Payment Required）を機械が交渉可能なフローに拡張します。サーバーが 402 を返すと、エージェントの決済ツールが価格を交渉し、バジェットを確認し、トランザクションに署名し、オーケストレーターが設定したポリシーと確認境界内でのみリトライします。

支出コントロール

すべての決済ツール呼び出しは SpendingPolicy を強制します：

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

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

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

MCP 統合

決済層は Claude Code またはエージェントハーネスのセットアップに組み込まれる標準 MCP ツールを公開します。

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

オプション A: agentwallet-sdk（Base / マルチチェーン）

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

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

注意: 支出ポリシーはエージェントへの委任前にオーケストレーターが設定します — エージェント自体では設定しません。これによりエージェントが独自の支出制限をエスカレーションするのを防ぎます。オーケストレーション層またはタスク前のフックで set_policy 経由でポリシーを設定し、エージェント呼び出し可能ツールとしては設定しないこと。

オプション B: OKX エージェント決済プロトコル（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 フローの場合、コードを生成する前に最新の言語固有ガイドを取得する：

現在の OKX リポジトリを確認せずに古いドキュメントの例をコピーしないこと。現在の OKX ガイダンスはディスパッチャーとして okx-agent-payments-protocol を使用しており、Java セラードキュメントが利用可能になっています。

オプション C: アップストリーム x402 パッケージ（Solana + Base/EVM）

エージェントが Solana、Base、またはアップストリームのプロトコル実装がサポートする他のネットワークで支払う（または API が課金する）場合にこのパスを使用します。x402-foundation/x402 の正規 x402 モノレポは活発にメンテナンスされており、クライアントとミドルウェアのパッケージを直接公開しています。オプション A・B と異なり、これは別個の MCP サーバーではありません — エージェント自身の HTTP クライアントをラップし、リソースサーバーが選んだファシリテーターが検証・決済します。

バイヤー側エージェントフローの場合：

1. 古いドキュメントのスニペットをコピーするのではなく、メンテナンスされている examples/typescript/clients（fetch、axios、MCP）の例から始める。
2. オプション B が OKX フローに要求するのとまったく同様に、最初の有料リクエストの署名または送信の前に明示的なユーザー確認を求める。汎用ツール呼び出しの背後に決済実行を隠さない。
3. パッケージバージョンを固定する（例：@x402/fetch@2.22.0）；アップストリームの全パッケージはロックステップでバージョニングされる。
4. バジェットはクライアントに登録した PaymentPolicy で強制し、毎回サーバーの実際のチャレンジに対して検査が走るようにする。自分で渡した数値と突き合わせるバジェットは何も証明しない — 金額・アセット・ネットワークはすべてサーバー由来なので、署名が生成される前に 3 つとも検証すること。

1. 受取先と予算のポリシーとは別に、許可するリソースのオリジンを正確に設定する。以下の支払い対応 fetch はすべてリダイレクトを拒否する。セッションの確認には許可オリジン、ネットワーク、資産、受取先、人が読める単位の支出上限を明示し、並行呼び出しは同じ確認結果を共有する。クライアントとポリシーはオーケストレーター内に留める。

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// Signer keys belong to the ORCHESTRATOR's env — never hardcoded, never agent-writable.
const evmKey = process.env.EVM_PRIVATE_KEY as `0x${string}`;
const svmKey = process.env.SVM_PRIVATE_KEY;
if (!evmKey || !svmKey) {
  throw new Error("Signer keys are not set — refusing to start payment client");
}

// One client, both network families: the buyer pays whichever chain the 402 offers.
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(evmKey)));
client.register("solana:*", new ExactSvmScheme(await createKeyPairSignerFromBytes(base58.decode(svmKey))));

// A PaymentPolicy filters the SERVER's payment requirements before any
// signature is created. Returning an empty array means "nothing here is
// acceptable" and the client refuses to pay rather than falling back.
const ALLOWED_NETWORKS = new Set([
  "solana:

ポリシーを登録すると、予算超過の金額、想定外のトークン、未登録のチェーンはすべてフェイルクローズドになる — 候補がすべて除外されるため、createPaymentPayload は署名せずに例外を投げる。デブネット USDC は 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU；開発時のみ ALLOWED_ASSETS に追加すること。ポリシーは敵対的にテストする — 5000000 アトミック単位を要求するチャレンジ、別のミントを提示するチャレンジ、登録していないチェーンのチャレンジを与え、いずれも署名が生成されないことを確認する。exact-SVM スキームではファシリテーターがトランザクション手数料支払者となるため、買い手のウォレットは USDC のみを保有すればよい — ガス用の SOL は不要。

ファシリテーターの選択。 ファシリテーターはリソースサーバーに代わって検証と決済を行うため、これは買い手ではなくリソースサーバーの判断である。委ねる信頼が小さい順に：

ホスト型を選ぶ場合は、ここに書かれた名前ではなくアップストリームドキュメントのファシリテーターリストから選ぶこと — メンテナンスされており、網羅的ではなく、カバレッジも変わる。執筆時点では Coinbase の CDP（全トランザクションに KYT/OFAC スクリーニング）、PayAI、Corbits、Dexter、Solvador などが掲載され、複数が EVM に加えて Solana メインネットをカバーしている。どれを選ぶ場合も、本番前に /supported エンドポイントでライブカバレッジを確認し、ネットワークを追加したときは再確認すること。

開示: このセクションは、掲載されているファシリテーターの 1 つである PayAI に関わる者が寄稿した。複数ある選択肢の 1 つとして記載しており、上記の自己ホストおよびアップストリームデフォルトのパスを意図的に先に挙げている。

セラー側（API がエージェントに課金する）。 アップストリームのミドルウェアを使用する；1 つのルートで Base と Solana を同時に提示できる（実行可能なバージョンは examples/typescript/servers を参照）：

Solana のセラー：payTo アドレスには先に正規のトークンアカウントが必要。 exact-SVM クライアントは findAssociatedTokenPda で payTo の関連トークンアカウント（ATA）を導出してそこに送金するが、それを作成はしない。その正確なアカウントが存在しないと決済はシミュレーション段階で失敗し、402 が transactionsimulationfailed を返す — クライアントのバグのように見えるが、実際は受取側アカウントの欠落である。導出したアドレス自体を確認すること — オーナーのトークンアカウントを走査するのは等価ではない。同じミントの非正規な補助アカウントがあると検査は通るのに、クライアントが対象とする ATA は依然として存在しないからだ：

import { findAssociatedTokenPda, TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";

const [ata] = await findAssociatedTokenPda({
  mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",   // USDC mainnet
  owner: payToAddress,
  tokenProgram: TOKEN_PROGRAM_ADDRESS,                     // TOKEN_2022_PROGRAM_ADDRESS for Token-2022 mints
});

次にそのアドレスが実在することを確認する — value: null なら存在せず、そこへの決済は失敗する：

curl -s https://api.mainnet-beta.solana.com -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo",
       "params":["<DERIVED_ATA>",{"encoding":"base64"}]}' \
  | jq '.result.value != null'

作成方法（作成者が少額のレントを負担し、支払者ではない）：

• コード上では @solana-program/token の getCreateAssociatedTokenIdempotentInstruction をオンボーディングフローに追加する — 冪等版なので再実行しても安全で、決定的に動作する唯一の方法。
• spl-token CLI で spl-token create-account --owner 。
• そのトークンを payTo に送金する方法も使えるが、送金側が作成インストラクションを含む場合に限る — ウォレットや spl-token transfer --fund-recipient は含める。ATA が無い状態への素の transferChecked は、決済と同じように失敗する。

これは新規プロビジョニングされたウォレットやカストディアルウォレットへの支払いで最も問題になりやすい。そうしたウォレットは対象アセットの ATA をまだ持っていないことが多い。

セラー：1 つの支払い承認につきルートは 1 回だけ実行する。 ミドルウェアは支払いを検証し、ハンドラーを実行し、その後で決済する。検証は承認を消費しない（消費するのは決済）ため、同じ署名済み支払いを同時に複数回送ると、毎回検証を通り、毎回ハンドラーが実行される。ファシリテーターが決済するのは 1 つのコピーだけで、残りはレスポンスなしの 402 を受け取るので、誰も無料で出力を得ることはない。しかしハンドラー内の副作用（LLM 呼び出し、ジョブのキュー投入、オンチェーントランザクション）はコピーごとに発生する。本番のセラー（Python x402 2.9.0、FastAPI）では、1 つの承認を同時に 3 回送ると、ハンドラーが 3 回実行され、決済は 1 回だった。ハンドラー内の有料呼び出しカウンターも同じように売上を過大に数えるので、決済後に数えること。検証から決済までのより広い競合については x402#1169 で議論されている。

各承認を、ファシリテーターが検証した後、ハンドラーが実行される前に、1 回だけ取得する。リソースサーバーの onAfterVerify フックはちょうどその時点で実行され、そこから返した abort はハンドラーを実行せずに 402 になる：

import { createHash } from "node:crypto";
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { getBase64Encoder, getTransactionDecoder } from "@solana/kit";
import { createClient } from "redis";

// Use a shared, durable, non-evicting claim store. Atomic insertion alone
// does not preserve claims after a store reset or eviction; test that operational
// contract separately before claiming durable replay protection.
// The claim store must never be what takes the seller down. With the offline
// queue disabled, a command sent while disconnected fails at once; the queue
// cap does the same when the store is connected but not replying; the error
// listener stops a client error from crashing the process; and the connection
// is made in the background, so startup never waits on it.
const redis = createClient({
  url: process.env.REDIS_URL,
  disableOfflineQueue: true,
  commandsQueueMaxLength: 1_000,
  socket: { connectTimeout: 2_000 },
});
redis.on("error", (err) => console.warn(`replay store: ${err.message}`))