mcp-x402-pay

@cryptoapis-io/mcp-x402-pay

これは x402 の購入者側です — エージェントがリソースの料金を支払うために使うツールです。API に料金を請求するマーチャントには、MCP ツールではなくミドルウェア SDK（@cryptoapis-io/x402-merchant-sdk）を使用します。

AI エージェントが x402 で保護された HTTP エンドポイントを見つけて支払うための MCP サーバーです。

• x402_pay — URL を取得し、サーバーが 402 Payment Required を返した場合は、CryptoAPIs 購入者サービスを通じて支払いを承認し、ローカルで署名して再試行し、支払い済みのレスポンスを返します。
• x402_discover — ファシリテーターの x402 リソースと価格のカタログを閲覧できます。これにより、エージェントは渡された API を呼び出すだけでなく、有料 API を見つけることができます。

ノンカストディアル： 秘密鍵はリクエストごとに渡され、プロセスの外に出ることはありません（HTTP サーバーはなく、stdio のみです）。

現在の対応状況： EVM（eip712、例：Base USDC）と Solana に対応しています。Tron、Bitcoin/UTXO、XRP、Kaspa は近日対応予定です。配線は済んでいますが、まだ有効化されていません。これらで支払うと、family_not_yet_supported（「近日対応予定」）という明確な結果が返されます。

実行

node dist/cli.js            # stdio MCP server (no --api-key at startup; keys are per-tool-call)

前提条件 — エージェントの walletId

x402_pay は CryptoAPIs のエージェントウォレット（walletId）から支払います。支払いの前に、ブロックチェーンとネットワークの組み合わせごとに一度だけ作成してください — 購入者 API への POST を1回行うと ID が返されます（ノンカストディアル：登録するのは公開アドレスのみです）。

curl -X POST https://ai.cryptoapis.io/x402/buyer/wallets \
  -H "x-api-key: $CRYPTOAPIS_API_KEY" -H "content-type: application/json" \
  -d '{"blockchain":"base","network":"eip155:8453","address":"0xYourAddress"}'
# → { "walletId": "…" }

network はCAIP-2 ID（eip155:8453、solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp など）でなければなりません。単なる名前は使用できません。また、address（どのチェーンでも使用可能。Solana/Kaspa では必須）または xpub（xpub 対応チェーン）のいずれか一方を指定してください。不正な本文には、明確な 400 malformed_request が返されます。返された ID を X402_WALLET_ID に設定するか、walletId を渡してください。

ツール：x402_pay

入力	必須	説明
url	✓	（ペイウォールで保護されている可能性がある）リソース
apiKey	✓	CryptoAPIs キー（X402_BUYER 機能）— 購入者の /authorize の呼び出しにのみ使用
walletId	✓	POST /wallets で取得したウォレットレコード ID（レジストリの _id）— オンチェーンアドレスではありません（アドレスを指定すると wallet_not_found が返されます）
privateKey	✓	ウォレットの EVM キー — ローカルで署名され、どこにも送信されません
method/body/headers		実行するリクエスト
allowedNetworks		支払い可能な CAIP-2 ネットワークを制限
maxAmount		安全上限 — 必要な最小単位額が上限を超える場合は拒否
allowedHosts		支払い可能なサイトを制限します。例：["api.acme.com"]（先頭にドットを付けるとサブドメインも対象）。リスト外の URL は、ネットワーク呼び出しの前に拒否されます。X402_ALLOWED_HOSTS（カンマ区切り）にフォールバックします — 許可リストをモデルがアクセスできない場所に保つため、ここに固定してください

{ status, paid, body, settlement? } を返します。許容できる支払い方法がない 402、または maxAmount を超える場合は、reason とともに paid:false を返します — 署名も支払いも行われません。

ツール：x402_discover

x402 の「Bazaar」— 登録済みの x402 リソースと各リソースの料金を閲覧します （仕様 §8）。

入力	必須	説明
type		リソースタイプで絞り込みます。例："http"
limit		ページサイズ。1～100（デフォルトは 20）
offset		ページ送りでスキップする行数（デフォルトは 0）
facilitatorBaseUrl		ファシリテーターを上書きします（QA/ローカル）

{ resources: [{ resource, type, x402Version, accepts, lastUpdated, metadata? }], pagination } を返します。

公開 — API キーもウォレットも不要で、支出もありません。そのため、常に安全に呼び出せます。accepts[].amount は最小単位（USDC は小数点以下 6 桁："10000" = $0.01）であることに注意してください。ユーザーに価格を提示する前に換算してください。選択した resource を x402_pay に渡すと、実際に購入できます。

フロー

1. fetch(url) を実行します。402 以外の場合は、そのまま返します。
2. 402 の場合は、accepts の項目を選択し（許可リストを考慮）、購入者の /authorize を通じて認証し、署名用アーティファクトを取得します。
3. ローカルで署名します（@cryptoapis-io/mcp-signer の evm_sign typed-data）。次に、x402 PaymentPayload を作成します （ワイヤースキームは常に exact で、ファミリーは network に含まれます）。
4. base64 の X-PAYMENT ヘッダーを付けて再試行し、支払い済みレスポンスと決済結果の X-PAYMENT-RESPONSE を返します。

セキュリティ

秘密鍵はツールのパラメーターであり、MCP クライアントによってログに記録されたり、会話履歴に保存されたりする可能性があります。信頼できるローカル環境でのみ使用してください。これは @cryptoapis-io/mcp-signer と同様です。