whale-data-mcp

@predge/whale-data-mcp

https://api.predge.io の Predge API（AI エージェントの支払いに対する署名付き配信判定、Polymarket のクジラ取引、スマートマネーのシグナル、署名付き証明、無料の署名付き UMA 決済リスク）をツールとして公開する MCP サーバーです。支払いは内部で処理されます。 有料ツールを呼び出すたびに、x402 クライアントが USDC のマイクロペイメントに署名します。エージェントはツールを呼び出すだけで、データを取得できます。資金を入金した購入者キーをご用意ください。

デフォルトでは Base メインネットを使用します（稼働中の Predge API はメインネット専用です）。有料ツールでは実際の USDCを使用します（通常は 1 回あたり $0.005～$0.03）。資金が動く前に MAX_PRICE_USD（デフォルトは $0.05）で上限が設定されます。残高を低く抑えた専用の購入者ウォレットを使用してください。

無料キーを取得する

1 分で取得できる無料のパイロットキー：https://predge.io/start（カード不要）

MCP サーバーを使用する場合：claude mcp add predge-whale-data -e PREDGE_KEY=pdg_pilot_... -- npx -y @predge/whale-data-mcp（キーで利用できる呼び出しにはウォレットは不要です。下記のオプション：Predge キーをご覧ください）。

最初の呼び出しはプレーン HTTP で行い、有料エージェント呼び出しに対する署名付き配信判定を取得します。

export PREDGE_KEY=pdg_pilot_...   # from predge.io/start
curl -s https://api.predge.io/v1/verdicts \
  -H 'content-type: application/json' \
  -H "x-predge-key: $PREDGE_KEY" \
  -d '{"job":{"endpoint":"https://api.example.com/v1/report","expected_content_type":"application/json","required_fields":["rows"]},
       "delivery":{"status":200,"headers":{"content-type":"application/json"},"body":"{\"rows\":[1]}"},
       "payment":{"amount_usd":0.25,"payer":"0xBuyer","payee":"0xMerchant"}}'

レスポンスには verdict（delivered / not_delivered / inconclusive）、reason_codes、ed25519 の attestation、および verify_url が含まれます。ドキュメント：predge.io/docs#verdicts。

キーがありませんか？x402 経由で呼び出しごとに支払うこともできます。同じリクエストから x-predge-key を省略すると、任意の x402 クライアントが USDC で支払える価格（$0.05）を示す 402 が返されます。

インストール（1 コマンド）

Claude Code：

claude mcp add predge-whale-data \
  -e BUYER_PRIVATE_KEY=0xYOUR_FUNDED_BASE_MAINNET_KEY \
  -e X402_NETWORK=base \
  -- npx -y @predge/whale-data-mcp

Claude Desktop / Cursor / 任意の MCP クライアント — クライアントの MCP 設定に追加します。

{
  "mcpServers": {
    "predge-whale-data": {
      "command": "npx",
      "args": ["-y", "@predge/whale-data-mcp"],
      "env": {
        "BUYER_PRIVATE_KEY": "0xYOUR_FUNDED_BASE_MAINNET_KEY",
        "X402_NETWORK": "base"
      }
    }
  }
}

これで完了です。エージェントは25 個のツール（有料ルート 18 個＋無料ツール 7 個：ディスカバリー、決済リスク、判定の再取得、判定レポート、キーの状態、Desk 設定、レコード検証）を利用できます。ディスカバリー、決済リスク、判定の再取得、レコード検証にはキーは必要ありません。アカウントも不要です。購入者キーを使って、Base または Solana 上で呼び出しごとに USDC を支払います。数ドル分の USDC を入金してください（ガス代はファシリテーターが支払うため、ETH／SOL は不要です）。

オプション：Predge キー（PREDGE_KEY）

PREDGE_KEY を設定すると、サーバーはすべてのリクエストで x-predge-key ヘッダーとして送信します。

• パイロットキー（無料）は https://predge.io/start から取得できます（メールアドレスが必要、カード不要）。決済見積もり（predge_settlement_estimate）と配信判定（predge_verdict）は 30 日間無料で、predge_verdict_report は署名付きの月次レポートを返します。 期間終了後、これらの呼び出しは再び 402 を返します。購入者キーがあれば、以降は呼び出しごとに支払います。
• Desk キーは https://predge.io/desk から取得できます（14 日間のトライアル）。predge_desk_config を利用できます。

claude mcp add predge-whale-data -e PREDGE_KEY=pdg_pilot_... -- npx -y @predge/whale-data-mcp

キーが優先されます。キーで利用できる呼び出しでは、購入者キーが設定されていても支払いは発生しません。キーも購入者ウォレットもない場合、有料ツールは不明瞭なエラーで失敗するのではなく、API の 402 の説明（価格、ネットワーク、支払い方法、パイロットキーの取得先）を返します。キーがログに記録されたり、ツールの結果に含まれたりすることはありません。

ElizaOS — キャラクターファイルに追加します（@fleek-platform/eliza-plugin-mcp 経由）。

{
  "plugins": ["@fleek-platform/eliza-plugin-mcp"],
  "settings": {
    "mcp": {
      "servers": {
        "predge": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@predge/whale-data-mcp"],
          "env": { "BUYER_PRIVATE_KEY": "0xYOUR_FUNDED_BASE_MAINNET_KEY", "MAX_PRICE_USD": "0.05" }
        }
      }
    }
  }
}

支出に上限を設けるには MAX_PRICE_USD を設定します。上限を超える呼び出しは、支払い前に拒否されます。完全な連携ガイド（ElizaOS、Claude、MCP 以外のスタック向けの生 x402、支出上限）：https://predge.io/docs#whale-data

ツール

ツール	価格	返される内容
predge_list_endpoints	無料	API の説明と、価格／スキーマ付きのすべてのエンドポイント（最初に呼び出してください）
predge_settlement_risk	無料	Polygon から読み取った、Polymarket の単一市場に関する署名済みのリアルタイム UMA 決済リスク。UMA の状態、現在の提案とチャレンジ期間、すべての異議申し立て、UMA 投票の状況、掲示板の更新、オンチェーンでの解決、risk_level（ok|watch|caution|resolved）、segment_dispute_rate、settlement_estimate_available が含まれます。settlement_estimate 自体は有料です：predge_settlement_estimate。このツールは ed25519 署名を再検証し、{ verification, record } を返します。パラメーター：market（condition id、数値の market id、または slug）。IP あたり毎分 60 リクエスト
predge_settlement_estimate	約$0.02、パイロットキーで 無料	settlement_estimate を含む、同じ署名済みの決済リスクレコード（2026 年の Polymarket UMA 異議申し立てに基づく統計であり、助言ではありません）。GET /v1/settlement-risk/:market/estimate。まず無料レコードの settlement_estimate_available を確認してください。{ verification, record } を返します。パラメーター：market
predge_verdict ⭐	$0.05 / $0.50、パイロットキーで 無料	配信判定：有料ジョブは配信されましたか？ job（約束された内容：endpoint、expected_content_type、json_schema、required_fields、max_latency_ms、expected_sha256 など）、delivery（証拠：status、headers、body または body_sha256、タイミング）、payment（amount_usd、tx_hash、network、payer、payee）、任意の agent / provider_agent（id、version、operator、authorization_ref）を送信します。payment.amount_usd が 1 未満の場合は POST /v1/verdicts（$0.05）、1 以上の場合は POST /v1/verdicts/large（$0.50。x402 経由で支払うには MAX_PRICE_USD を 0.5 以上にする必要があります）。署名済み判定（delivered | not_delivered | inconclusive）、チェックごとの結果、理由コード、返金の推奨を { verification, record } として返します
predge_get_verdict	無料	GET /v1/verdicts/:id：保存された署名済み判定を再取得し、再検証します。パラメーター：id（vrd_ + 24 文字）
predge_verdict_report	無料、PREDGE_KEY が必要	GET /v1/verdicts/report：このキーでリクエストした判定に関する、署名済みの月次異議申し立て対応レポート（件数、返金の推奨、理由コード、判定までの時間、判定 ID）。パラメーター：month（YYYY-MM）、merchant_id、limit、cursor、sample
predge_key_status	無料、PREDGE_KEY が必要	GET /v1/me：キーのプラン、クォータ、パイロットの有効期限
predge_desk_config	無料、Desk キーが必要	GET /v1/desk/config：監視対象のウォレット、アラートの送信先（webhook、Telegram）、プランの状態
predge_verify_record	無料	任意の Predge 署名済みレコード（predge-attest-v1）をオフラインで検証します：C(payload) == canonical、sha256(canonical) == content_hash、ed25519 署名、envelope_signature、および署名者が predge-keys.json に有効な状態で掲載されていること。パラメーター：record（JSON 文字列）
predge_whales_latest	約$0.005	最新のクジラ取引（$10k 以上、15 分遅延）。パラメーター：limit（1-100）
predge_whale_market	約$0.01	単一市場の 7 日間のクジラ活動。パラメーター：condition_id
predge_signals_daily	約$0.02	24 時間のダイジェスト：上位市場、純フロー、最大の賭け
predge_wallets_leaderboard	約$0.01	解決済み市場での優位性に基づくウォレットのランキング。パラメーター：window（7d|30d）、limit
predge_wallet_profile	約$0.01	ウォレットのスコア、勝率、カテゴリ、直近 20 件の取引。パラメーター：address
predge_markets_movers	約$0.005	YES 価格の最大変動。パラメーター：window（1h|6h|24h）
predge_signals_consensus	約$0.03	優位性を検証したスマートマネーの純フローと市場ごとの方向
predge_attest ⭐	約$0.02	主力機能。 解決済み結果の証明 — 市場の確定した真実（resolved、resolution、resolved_at）。任意の side（yes|no）で、過去のシグナル／勝率に関する主張が実際に正しかったかを確認できます。パラメーター：condition_id、side
predge_sports_attest ⭐	約$0.02	主力機能。 ESPN から取得した、確定済み試合結果の Ed25519 署名付きデータ（勝者、最終スコア、completed）。Predge の公開鍵を使ってオフラインで検証できます。任意の winner（チーム略称）を指定すると correct が返されます。改ざん防止された真実に基づいて賭けを決済したり、実績を証明したりできます。リーグ：nba、wnba、nfl、college-football、mlb、nhl、mls、epl、champions-league、laliga。パラメーター：league、event_id、winner
predge_bets_biggest	約$0.005	全市場の単一取引の上位 20 件。パラメーター：window（24h|7d）
predge_signals_daily_category	約$0.01	単一カテゴリに絞った 24 時間のダイジェスト。パラメーター：category
predge_signals_consensus_category	約$0.02	単一カテゴリに絞ったコンセンサス。パラメーター：category
predge_signals_market	約$0.01	単一市場のスマートマネー判定（「この動きを信頼できますか？」）。パラメーター：condition_id
predge_wallet_history	約$0.02	ウォレットの取引履歴と、累積勝率および損益曲線。パラメーター：address、window（30d|90d|all）
predge_wallets_compare	約$0.02	2～10 個のウォレットを並べて比較し、市場の重複も確認します。パラメーター：addresses
predge_market_history	約$0.01	単一市場の価格／出来高の履歴。パラメーター：condition_id、window（7d|30d|all）
すべての有料結果には、オンチェーン決済トランザクションを記載した注記が含まれます。ツールとしては公開されていません
（raw x402/HTTP からアクセスできます。predge_list_endpoints を参照）：/v1/markets/:id/edge のポーリングパルス、/v1/onchain/* ルート、署名付きコール／
ステーク／トラックレコードの各ルートです。一時停止中のルート（503 signed_wallet_outputs_paused）にはツールがありません。ウォレットのトラックレコード証明 /v1/wallets/:address/attest（
predge_wallet_attest ツールは 0.3.0 で削除されました）、/v1/onchain/pm-activity、
/v1/onchain/pm-flows、無料の /v1/signal/:address が該当します。

署名付きレコードを自分で検証する

Predge の署名付きレコードにはすべて、attestation エンベロープが含まれます。ルールは data.predge.io/canonicalization.md で公開されています。 canonical は、すべての階層でキーをソートし、空白を含まない JSON としてのペイロードです。 content_hash = sha256(canonical) です。signature は canonical の UTF-8 バイト列に対する ed25519 署名です。 署名者は、https://api.predge.io/.well-known/predge-keys.json にある有効なキーでなければなりません （attestation kid は 13fa3d18a369e6c7）。src/verify.ts は node:crypto のみを使ってこれを実装しています。

設定（env）

有料ツールを利用するには、少なくともいずれか1つの決済レールに資金を入れたキーが必要です。Base（BUYER_PRIVATE_KEY） および／または Solana（SOLANA_BUYER_SECRET）を指定できます。有料ルートの 402 オファーには両方のネットワークが含まれます。 クライアントは、キーを持つネットワークで決済します（両方のキーがある場合は、より安価な方が選ばれます）。決済代行業者がどちらのレールでもネットワーク手数料を負担するため、ウォレットに必要なのは USDC のみです。

Var	Default	Notes
PREDGE_KEY	—	オプション。Pilot キー（predge.io/start）または Desk キー（predge.io/desk）です。すべてのリクエストで x-predge-key として送信されます。ログには記録されません。上記を参照してください。
BUYER_PRIVATE_KEY	—	Base レール用の、資金を入れたBaseメインネット EVM キー（0x…）です。
SOLANA_BUYER_SECRET	—	オプション。Solana レール用の、資金を入れたSolanaメインネットキー（64個の数値を含む JSON 配列または base58）です。
X402_NETWORK	base	Base ネットワーク：base はメインネット（実際の USDC）、base-sepolia はテストネットへのデプロイに対してのみ使用します。
X402_SOLANA_NETWORK	X402_NETWORK と一致	solana（メインネット）または solana-devnet です。
SOLANA_RPC_URL	@x402/svm default	オプションのカスタム Solana RPC です（パブリックの mainnet-beta にはレート制限があります）。
PREDGE_BASE_URL	https://api.predge.io	別のデプロイ先を指定するための上書き設定です。別名として PREDGE_API_URL も使用できます。署名は常に api.predge.io のキーセットに対して検証されます。
MAX_PRICE_USD	0.05	この金額を超える価格の呼び出しは、支払いの前に拒否されます。
PREDGE_MCP_USER_AGENT	predge-whale-data-mcp/<version>	すべてのリクエストで送信されます（API が MCP トラフィックを識別できるようにします）。

predge_list_endpoints、predge_settlement_risk、predge_get_verdict、predge_verify_record は、キーなしで動作します。

0.1.10 以前からのアップグレード： これらのバージョンでは、廃止された API ホストがデフォルトで使われるため、すべての呼び出しが 404 で失敗します。0.2.0 にアップグレードするか（npx -y @predge/whale-data-mcp@latest）、 PREDGE_BASE_URL=https://api.predge.io を設定してください。

テストネット

実際のお金を使わずに決済フローを試すには、PREDGE_BASE_URL を API の Base-Sepolia デプロイ先に設定し、X402_NETWORK=base-sepolia を指定します。購入者のウォレットには faucet.circle.com から資金を入れてください（公開中の本番 API はメインネット専用のため、テストネットには独自のデプロイが必要です）。

安全性

• 価格上限 — MAX_PRICE_USD は支払い選択時に適用されるため、上限を超える呼び出しは支払いが発生する前に拒否されます（リクエストが無駄になることはありません）。
• ネットワークガード — クライアントは設定されたネットワーク上の要件に対してのみ支払います。テストネットモード中にメインネットの要件を誤って決済することはありません（また、その逆もありません）。
• 環境変数以外でのキーの取り扱いなし — サーバーは BUYER_PRIVATE_KEY を環境変数から読み取り、ログには記録せず、ローカルの署名者以外に送信することもありません。残高の少ない専用ウォレットを使用し、キーをバージョン管理に含めないでください。 PREDGE_KEY は Predge API へのリクエストヘッダー x-predge-key にのみ設定され、ログに記録されることはありません。また、キーを含む API エラーが返された場合は、キーが伏せられます。

ソースから実行する

git clone https://github.com/predgeAI/whale-data-mcp.git
cd whale-data-mcp && npm install && npm run build
# then point your MCP client's "command" at node with args ["/abs/path/whale-data-mcp/dist/index.js"]

ローカルで検証する

npm test                                               # unit tests (no network, no payment)
npm run inspect                                        # list tools (no payment)
node dist/dev-list-tools.js predge_list_endpoints      # free call against prod
node dist/dev-list-tools.js predge_settlement_risk '{"market":"<condition id or slug>"}'   # free, signed
# paid call (spends real USDC on mainnet):
BUYER_PRIVATE_KEY=0x… X402_NETWORK=base node dist/dev-list-tools.js predge_whales_latest '{"limit":2}'