# Predge Whale Data

> Polymarket whale trades and smart-money signals as pay-per-call HTTP endpoints. No API keys, no accounts: every paid request is paid with USDC over the x402 protocol (v2) at request time, $0.005–$0.03 per call. Built on the whale-tracking pipeline behind @predge_alerts_bot.

Key facts:

- API base URL: https://x402-api-production-266e.up.railway.app (GET / returns a free machine-readable self-description — always the source of truth)
- Payment: x402 v2, scheme "exact", USDC. Network: Base mainnet (eip155:8453), USDC asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, payTo 0x9084f5000e07c7133d6da5ee4f271ab6d1821144, facilitator https://facilitator.payai.network. Parameters are advertised live in GET / and in every 402 — always re-read them over cached docs.
- Flow: request a paid endpoint → 402 with base64 JSON in the PAYMENT-REQUIRED response header → sign an EIP-3009 USDC authorization for accepts[0] → retry the same request with the PAYMENT-SIGNATURE header → 200 with data + PAYMENT-RESPONSE header (settle receipt with on-chain tx hash). Client libraries do this automatically: @x402/fetch + @x402/evm (JS/TS) or `npx x402-proxy <url>` (shell). The buyer wallet needs USDC on Base only (a dollar goes a long way at these prices) — the facilitator pays gas, no ETH required.
- Paid endpoints (GET, price per call): /v1/whales/latest?limit=50 ($0.005, latest whale trades >= $10,000); /v1/whales/market/{conditionId} ($0.01, 7-day whale activity for one market); /v1/bets/biggest?window=24h ($0.005, top-20 largest single trades across all markets, 24h|7d); /v1/signals/daily ($0.02, 24h digest: top markets, net flow, largest bets); /v1/signals/consensus ($0.03, smart-money score>70 net flow + direction per market, 24h); /v1/wallets/leaderboard?window=30d&limit=50 ($0.01, wallets ranked by realized win rate, resolved markets only); /v1/wallets/{address} ($0.01, wallet profile: score, win rates, categories, last 20 trades); /v1/wallets/{address}/history?window=30d ($0.02, wallet trade history + running win-rate & modeled-PnL curve, resolved markets only); /v1/wallets/compare?addresses=0x..,0x.. ($0.02, side-by-side 2-10 wallets + market overlap); /v1/markets/movers?window=6h ($0.005, largest YES-price moves from trade prints, 1h|6h|24h); /v1/markets/{conditionId}/history?window=30d ($0.01, price/volume history for one market, 7d|30d|all). Full sweep of all 11 endpoints: $0.145. Free: GET /, GET /health.
- Honest-data rules: paid data is delayed 15 minutes (real-time stays exclusive to Predge Pro at https://t.me/predge_alerts_bot); aggregates return {"insufficient_data": true, "reason": ...} instead of pretending when the dataset is too young (still charged — the answer is honest, not empty); win rates count RESOLVED markets only; /v1/markets/movers prices come from trade prints, not orderbook quotes; 4xx/5xx responses are never charged (settlement happens only after a successful handler response); unknown wallets → 404, not charged.
- Limits: 10 requests/sec per IP on /v1/*; server-side response cache 60 s (whales, movers) to 5 min (other aggregates).

## Docs

- [API reference and quickstart](https://data.predge.io/): human docs for all endpoints, payment walkthrough, copy-paste agent prompt
- [OpenAPI 3.1 spec](https://data.predge.io/openapi.json): full request/response schemas with examples
- [x402 discovery document](https://data.predge.io/.well-known/x402): all 11 resources with live payment requirements and Bazaar discovery metadata, regenerated from the live 402 responses

## Try it

- Free, no wallet: `curl -i "https://x402-api-production-266e.up.railway.app/v1/whales/latest?limit=5"` → inspect the PAYMENT-REQUIRED header (base64 JSON: price, asset, payTo, plus an example response body)
- Paid, one line: `npx x402-proxy "https://x402-api-production-266e.up.railway.app/v1/whales/latest?limit=5"` (needs a funded buyer key; see quickstart)

## Optional

- [Predge Pro alerts bot](https://t.me/predge_alerts_bot): the real-time Telegram product this API's pipeline powers
- [Predge news channel](https://t.me/predge_news): release announcements
- [Predge on X](https://x.com/PredgeAI): announcements and ecosystem updates (@PredgeAI)

## 中文说明 (Chinese)

Predge Whale Data：面向 AI agent 的 Polymarket 鲸鱼情报 API，按次付费，无需 API key、无需注册。核心差异：不只告诉你「谁下注大」，而是「谁真正会赢」——每个钱包按实际胜率评分，仅统计已结算市场的真实结果（不用活跃度启发式，不算未实现盈亏），聪明钱共识只统计经验证的赢家（评分 > 70）。

- 支付：x402 协议 v2，USDC，Base 主网（eip155:8453），每次调用 $0.005–$0.03。买家钱包只需 USDC，无需 ETH——gas 由 facilitator 通过 EIP-3009 代付。流程：请求任一付费端点 → 402 响应的 PAYMENT-REQUIRED 头（base64 JSON）给出准确价格与收款地址 → 用 @x402/fetch 等客户端签名并自动重试 → 200 返回数据 + PAYMENT-RESPONSE 头（含链上结算交易哈希）。
- 11 个付费端点：最新鲸鱼交易（≥ $10,000）；单一市场 7 天鲸鱼动向；全市场最大单笔交易 Top-20（24h/7d）；24 小时摘要；聪明钱共识（旗舰）；钱包胜率排行榜；钱包画像；钱包交易历史 + 胜率与模型化盈亏曲线（仅已结算市场）；多钱包对比（2-10 个）+ 共同持仓；价格异动（1h/6h/24h）；单一市场价格/成交量历史（7d/30d/all）。全部 11 个端点扫一遍共 $0.145。免费：GET /（服务自描述——实时价格与网络参数以此为准）、GET /health。
- 诚实数据规则：付费数据延迟 15 分钟（实时信号为 Predge Pro 专属：https://t.me/predge_alerts_bot）；数据不足时返回 {"insufficient_data": true, "reason": ...} 而非假装有答案；胜率只计已结算市场；4xx/5xx 错误不收费。
- API base：https://x402-api-production-266e.up.railway.app · 英文文档：https://data.predge.io/ · OpenAPI：https://data.predge.io/openapi.json · X：https://x.com/PredgeAI