whale-data-mcp

@predge/whale-data-mcp

将 Predge API https://api.predge.io 作为工具提供的 MCP 服务（AI Agent 付款的签名交付判定、Polymarket 巨鲸交易、聪明资金信号、签名证明，以及免费的签名 UMA 结算风险）。付款在后台处理： 每次付费工具调用都会通过 x402 客户端签署一笔 USDC 小额付款 — Agent 只需调用工具并获取数据。你需要提供已注资的买方密钥。

默认使用 Base 主网（实时 Predge API 仅支持主网）。付费工具会消耗真实 USDC — 通常每次调用 $0.005–$0.03，且在任何资金转移之前，最高限额为 MAX_PRICE_USD（默认值为 $0.05）。请使用余额较低的专用买方钱包。

获取免费密钥

一分钟即可获取免费试用密钥：https://predge.io/start（无需银行卡）

使用 MCP 服务：claude mcp add predge-whale-data -e PREDGE_KEY=pdg_pilot_... -- npx -y @predge/whale-data-mcp（该密钥涵盖的调用无需钱包，详见下文可选：Predge 密钥）。

首次通过纯 HTTP 调用：获取付费 Agent 调用的签名交付判定。

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，会返回 402 和价格（$0.05），可由任意 x402 客户端使用 USDC 支付。

安装（一条命令）

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"
      }
    }
  }
}

就这么简单 — Agent 即可使用 25 个工具（18 个付费路由 + 7 个免费工具：发现、结算风险、重新读取判定、判定报告、密钥状态、Desk 配置、记录验证）。发现、结算风险、重新读取判定和记录验证完全无需密钥。无需账户；买方密钥会在 Base 或 Solana 上按次支付 USDC。为其注入几美元的 USDC 即可（Gas 由付款协调方支付，因此不需要 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、数字市场 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）
每个付费结果都附有一条链上结算交易备注。以下内容不会作为工具公开
（原始 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 实现此功能。

配置（环境变量）

付费工具需要至少为一条支付通道预存资金的密钥——Base（BUYER_PRIVATE_KEY） 和／或 Solana（SOLANA_BUYER_SECRET）。每个付费路由的 402 报价都包含两个网络； 客户端会使用持有其密钥的网络付款（若两个密钥都有，则选择更便宜的网络）。支付服务商会承担任一通道的网络费用——钱包只需持有 USDC。

变量	默认值	说明
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 默认值	可选的自定义 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 指向 Base-Sepolia 上的 API 部署，并设置 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}'