x402 Research

x402-research-mcp

x402-research の従量課金 API 用 MCP（stdio）サーバーです。 デフォルトではテストネット（Base Sepolia）を使用します。X402_NETWORK=eip155:8453 を明示的に設定した場合に限り、Base メインネットを使用します。 公開元がキーを保持することはありません。支払いには、環境変数でユーザー自身が指定したウォレットキーを使用し、1 回あたりおよびセッションあたりの上限が適用されます。

警告

専用の残高が少ないウォレットを使用し、メインのウォレットは絶対に使用しないでください。 このサーバー専用の新しいキーを作成し、数 USDC のみを入金してください（メインネットでは、セッション上限を少し上回る額を入金してください）。MCP クライアントの設定やこのプロセスの環境変数を読み取れる人やものは、誰でもそのウォレットの資金を使用できます。上限が制限するのは、このサーバーが署名する金額であり、キーが漏えいした場合に可能なことではありません。

ツール（1 回あたりの価格、Base 上の USDC、/llms.txt より）

ツール	ルート	価格
signal(asset)	GET /api/signal/{asset}	0.003
signal_batch(assets[≤10])	GET /api/signal-batch?assets=	0.02
brief(asset)	GET /api/brief/{asset}	0.03
risk_snapshot(address)	GET /api/firm/risk-snapshot?address=	0.03
invoice_decode(header)	POST /api/x402/invoice-decode	0.02
settlement_status(tx)	GET /api/x402/settlement-status?tx=	0.02
approval_enumerate(address)	GET /api/x402/approval-enumerate?address=	0.03
preflight(address, invoice?)	GET /api/x402/preflight?address=[&invoice=]	0.05
session_status()	ローカル	無料

対象資産：btc eth sol xrp doge ada avax link dot ltc bch uni aave xlm hbar shib sui near atom fil。 有料ツールはすべて preview: true（402 の条件を返し、支払いは行いません）と max_price_usdc にも対応しています。

安全性

• プレビューモードは、X402_BUYER_PRIVATE_KEY が未設定の場合、または X402_PREVIEW=1 の場合に有効になります。ツールはデコード済みの 402 の条件を返し、署名は行いません。
• 1 回あたりの上限 X402_MAX_PRICE_USDC（デフォルトは 0.10）。ツールの max_price_usdc で上限を引き下げることはできますが、引き上げることはできません。
• セッション上限 X402_SESSION_CAP_USDC（デフォルトは 0.50）。支出額が上限を超えることになる呼び出しは、署名前に拒否されます。支出額は署名済みの支払いを送信した時点で計上されます。サーバープロセスを再起動するとリセットされます。
• 提示額が広告価格を超える場合、別のネットワーク上にある場合、スキームが exact でない場合、または正規の USDC 資産でない場合、オファーは拒否されます。
• payTo 許可リスト（ハードコード）： signal、signal_batch、brief の支払い先は 0xacfca8bc6567e7db35ad8c814756695dad1cfb30 のみです。risk_snapshot、invoice_decode、settlement_status、approval_enumerate、preflight の支払い先は 0xa26f179e42836bc4ae0cea997fdfc9602d5b8147 のみです。X402_RESEARCH_URL の参照先にかかわらず、これ以外の受取先はすべて拒否されます。
• サーバーが環境変数やキーをログに記録することはなく、エラーメッセージに設定内容が含まれることもありません。
• 事前署名済みの支払いを渡す方法はありません。すべての支払いは、上記の上限のもと、このサーバーによって署名されます。
• 少額の USDC のみを保有する専用のホットウォレットを使用してください。キーはローカルプロセス内に保持され、ログに記録されたり返されたりすることはありません。

設定

変数	デフォルト
X402_NETWORK	eip155:84532（Base Sepolia）。Base メインネットを使用するには eip155:8453 を設定します
X402_RESEARCH_URL	https://x402-research-iota.vercel.app（メインネット専用。テストネットでは Sepolia へのデプロイが必要です）
X402_BUYER_PRIVATE_KEY	未設定 → プレビューのみ
X402_MAX_PRICE_USDC / X402_SESSION_CAP_USDC	0.10 / 0.50
X402_PREVIEW	未設定（1 にするとプレビューを強制）

インストール

Claude Desktop（claude_desktop_config.json）または Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "x402-research": {
      "command": "npx",
      "args": ["-y", "@agentfirm402/x402-research-mcp"],
      "env": {
        "X402_NETWORK": "eip155:8453",
        "X402_PREVIEW": "1"
      }
    }
  }
}

まずはプレビューモードで起動します。支払いを有効にするには、X402_PREVIEW を削除し、"X402_BUYER_PRIVATE_KEY": "0x…"（残高の少ない専用ウォレットを使用し、メインのウォレットは絶対に使用しないでください）を追加します。必要に応じて "X402_SESSION_CAP_USDC": "0.25" も追加できます。

テスト

npm test は、使い捨てキーと資金を使用せず、ローカルのモックに対してオフラインで実行されます。各チェックでのユニットテストによる拒否、キーなしでのプレビュー、および /0x[0-9a-fA-F]{64}/ に一致する文字列が stdout と stderr のすべてに含まれないことを grep で確認する stdio 漏えいテストを実行します。 npm run test:mainnet-preview は、メインネット上で 402 呼び出しをライブでプレビューモードで実行し、支払いは行いません。

リリース

依存関係は厳密に固定され、ロックファイルがコミットされています。公開は .github/workflows/mcp-publish.yml（手動実行、npm publish --provenance）でのみ行われます。

情報提供のみを目的としています。金融に関する助言ではありません。MIT。