{ "openapi": "3.1.0", "info": { "title": "Predge Whale Data API", "version": "2026.07.19", "summary": "Polymarket whale trades and smart-money signals, sold per-call over the x402 payment protocol.", "description": "Polymarket whale trades and aggregated whale signals from the Predge tracking pipeline (@predge_alerts_bot), sold per-call over the x402 payment protocol (v2). No API keys, no accounts — every paid request is paid with USDC at request time.\n\n**How payment works:** request any paid endpoint without payment and you get `402 Payment Required` with a `PAYMENT-REQUIRED` response header (base64-encoded JSON: exact price, asset, pay-to address, network). Sign an EIP-3009 USDC authorization for that amount and retry the same request with the `PAYMENT-SIGNATURE` header. The server verifies and settles through an x402 facilitator (the facilitator pays gas — the buyer wallet needs USDC only, no ETH) and answers `200` with the data plus a `PAYMENT-RESPONSE` header containing the settle receipt (incl. on-chain transaction hash). x402 client libraries (`@x402/fetch` + `@x402/evm` for JS/TS, or `npx x402-proxy` in a shell) do all of this automatically.\n\n**Honest-data guarantees:** paid data is delayed 15 minutes (real-time stays exclusive to Predge Pro, https://t.me/predge_alerts_bot); aggregate endpoints return `{\"insufficient_data\": true, \"reason\": ...}` instead of pretending when the dataset is too young; win rates count RESOLVED markets only; price movers are derived from trade prints, not orderbook quotes; error responses (4xx/5xx) are never charged — settlement happens only after a successful handler response.\n\n**Limits:** 10 requests/sec per IP on `/v1/*`. Responses are cached server-side (60 s for whales/movers, 5 min for the other aggregates).\n\nThis document is maintained by hand from the live 402 discovery metadata; the live service is the source of truth — `GET /` returns a full self-description and every 402 carries the current price and payment requirements.", "contact": { "name": "Predge", "url": "https://t.me/predge_alerts_bot", "email": "hello@predge.io", "x-twitter": "https://x.com/PredgeAI" } }, "servers": [ { "url": "https://x402-api-production-266e.up.railway.app", "description": "Production (settling on Base mainnet, eip155:8453)" } ], "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "networkName": "base (mainnet)", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "assetSymbol": "USDC", "assetDecimals": 6, "payTo": "0x9084f5000e07c7133d6da5ee4f271ab6d1821144", "facilitator": "https://facilitator.payai.network", "maxTimeoutSeconds": 60, "headers": { "paymentRequired": "PAYMENT-REQUIRED", "paymentSignature": "PAYMENT-SIGNATURE", "paymentResponse": "PAYMENT-RESPONSE" }, "discovery": "/.well-known/x402", "funding": "The buyer wallet needs USDC on Base only — no ETH; the facilitator pays gas via EIP-3009" }, "tags": [ { "name": "whales", "description": "Individual whale trades (>= $10,000 notional)" }, { "name": "signals", "description": "Aggregated whale and smart-money signals" }, { "name": "wallets", "description": "Wallet scoring, win rates and profiles" }, { "name": "markets", "description": "Market-level price movement" }, { "name": "meta", "description": "Free service endpoints (no payment)" } ], "paths": { "/v1/whales/latest": { "get": { "operationId": "getLatestWhaleTrades", "tags": [ "whales" ], "summary": "Latest whale trades", "description": "Latest Polymarket whale trades (15 min delay). Trades >= $10,000 notional with market, side, size, price, wallet address and Predge wallet score (0-100, 30d win rate). Source: Predge whale-tracking pipeline (@predge_alerts_bot).", "x-x402": { "priceUSD": "0.005", "amountAtomic": "5000" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max trades to return (1-100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Paid response with the latest whale trades.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of trades returned" }, "delay_minutes": { "type": "integer", "description": "Server-side data delay applied to paid responses" }, "whale_min_usd": { "type": "number", "description": "Current whale threshold in USD notional" }, "trades": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } } }, "required": [ "count", "delay_minutes", "whale_min_usd", "trades" ] }, "example": { "count": 1, "delay_minutes": 15, "whale_min_usd": 10000, "trades": [ { "platform": "polymarket", "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "market_title": "Will the Fed cut rates in September?", "market_slug": "fed-rate-cut-september", "category": "economics", "side": "yes", "price": 0.62, "size_usd": 25400, "wallet": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "wallet_score": 81, "wallet_win_rate_30d": 0.67, "tx_hash": "0x6a7de5…", "block_timestamp": "2026-07-17T09:41:02.000Z" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/whales/market/{conditionId}": { "get": { "operationId": "getMarketWhaleActivity", "tags": [ "whales" ], "summary": "7-day whale activity for one market", "description": "Whale activity for one Polymarket market over the last 7 days (15 min delay). Returns market info, aggregate whale volume, YES/NO split, net flow, unique whale wallets, and up to 200 trades.", "x-x402": { "priceUSD": "0.01", "amountAtomic": "10000" }, "parameters": [ { "name": "conditionId", "in": "path", "required": true, "description": "Polymarket condition id (0x… 32-byte hex)", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } ], "responses": { "200": { "description": "Paid response with per-market whale aggregates and trades.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "object", "properties": { "condition_id": { "type": "string" }, "platform": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "yes_price": { "type": "number" }, "status": { "type": "string" } } }, "window_days": { "type": "integer" }, "summary": { "type": "object", "properties": { "whale_trades": { "type": "integer" }, "whale_volume_usd": { "type": "number" }, "yes_volume_usd": { "type": "number" }, "no_volume_usd": { "type": "number" }, "net_flow_usd": { "type": "number", "description": "yes_volume_usd - no_volume_usd" }, "unique_wallets": { "type": "integer" } } }, "trades": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/Trade" } } }, "required": [ "market", "window_days", "summary", "trades" ] }, "example": { "market": { "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "platform": "polymarket", "title": "Will the Fed cut rates in September?", "category": "economics", "yes_price": 0.62, "status": "active" }, "window_days": 7, "summary": { "whale_trades": 14, "whale_volume_usd": 412000, "yes_volume_usd": 290000, "no_volume_usd": 122000, "net_flow_usd": 168000, "unique_wallets": 9 }, "trades": [ { "platform": "polymarket", "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "market_title": "Will the Fed cut rates in September?", "market_slug": "fed-rate-cut-september", "category": "economics", "side": "yes", "price": 0.62, "size_usd": 25400, "wallet": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "wallet_score": 81, "wallet_win_rate_30d": 0.67, "tx_hash": "0x6a7de5…", "block_timestamp": "2026-07-17T09:41:02.000Z" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bets/biggest": { "get": { "operationId": "getBiggestBets", "tags": [ "whales" ], "summary": "Biggest single bets", "description": "Largest single trades by notional across ALL Polymarket markets in the window (15 min delay). Same trade shape as /v1/whales/latest, sorted by size_usd descending, top-20. Live (unresolved) flow — outcome_verified: false.", "x-x402": { "priceUSD": "0.005", "amountAtomic": "5000" }, "parameters": [ { "name": "window", "in": "query", "required": false, "description": "Lookback window (default 24h)", "schema": { "type": "string", "enum": [ "24h", "7d" ], "default": "24h" } } ], "responses": { "200": { "description": "Paid response with the biggest bets.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string" }, "outcome_verified": { "type": "boolean", "description": "Always false: live, unresolved flow." }, "bets": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/Trade" } } }, "required": [ "window", "bets" ] }, "example": { "window": "24h", "outcome_verified": false, "bets": [ { "platform": "polymarket", "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "market_title": "Will the Fed cut rates in September?", "category": "economics", "side": "yes", "price": 0.62, "size_usd": 184000, "wallet": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "wallet_score": 81, "block_timestamp": "2026-07-22T04:11:00.000Z" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/signals/daily": { "get": { "operationId": "getDailySignalsDigest", "tags": [ "signals" ], "summary": "24h whale digest", "description": "Aggregated 24h whale digest for Polymarket (15 min delay): top-10 markets by whale volume with YES/NO net flow, top-10 largest single bets, and totals (whale trade count, volume, unique wallets). One call = full daily picture.", "x-x402": { "priceUSD": "0.02", "amountAtomic": "20000" }, "responses": { "200": { "description": "Paid response with the 24h digest.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "window_hours": { "type": "integer" }, "generated_at": { "type": "string", "format": "date-time" }, "totals": { "type": "object", "properties": { "whale_trades": { "type": "integer" }, "whale_volume_usd": { "type": "number" }, "unique_wallets": { "type": "integer" }, "markets_touched": { "type": "integer" } } }, "top_markets": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "condition_id": { "type": "string" }, "platform": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "whale_trades": { "type": "integer" }, "whale_volume_usd": { "type": "number" }, "yes_volume_usd": { "type": "number" }, "no_volume_usd": { "type": "number" }, "net_flow_usd": { "type": "number" } } } }, "largest_bets": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Trade" } } }, "required": [ "window_hours", "generated_at", "totals", "top_markets", "largest_bets" ] }, "example": { "window_hours": 24, "generated_at": "2026-07-17T10:00:00.000Z", "totals": { "whale_trades": 87, "whale_volume_usd": 2310000, "unique_wallets": 41, "markets_touched": 23 }, "top_markets": [ { "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "platform": "polymarket", "title": "Will the Fed cut rates in September?", "category": "economics", "whale_trades": 14, "whale_volume_usd": 412000, "yes_volume_usd": 290000, "no_volume_usd": 122000, "net_flow_usd": 168000 } ], "largest_bets": [ { "platform": "polymarket", "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "market_title": "Will the Fed cut rates in September?", "market_slug": "fed-rate-cut-september", "category": "economics", "side": "yes", "price": 0.62, "size_usd": 25400, "wallet": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "wallet_score": 81, "wallet_win_rate_30d": 0.67, "tx_hash": "0x6a7de5…", "block_timestamp": "2026-07-17T09:41:02.000Z" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/wallets/leaderboard": { "get": { "operationId": "getWalletLeaderboard", "tags": [ "wallets" ], "summary": "Top wallets by realized win rate", "description": "Top Polymarket wallets ranked by realized win rate over a 7d or 30d window. Win rate is computed from RESOLVED markets only (a trade wins when its side matches the final resolution); wallets need >= 10 trades in the window and at least one decided trade. Honest degradation: `{\"insufficient_data\": true, \"reason\": ...}` when the dataset is too young.", "x-x402": { "priceUSD": "0.01", "amountAtomic": "10000" }, "parameters": [ { "name": "window", "in": "query", "required": false, "description": "Ranking window (default 30d)", "schema": { "type": "string", "enum": [ "7d", "30d" ], "default": "30d" } }, { "name": "limit", "in": "query", "required": false, "description": "Max wallets to return (1-100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Paid response with the ranked wallets (or an honest insufficient_data envelope; both are charged).", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d" ] }, "min_trades": { "type": "integer" }, "insufficient_data": { "type": "boolean" }, "reason": { "type": "string", "description": "Present when insufficient_data is true" }, "wallets": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "score": { "type": [ "integer", "null" ], "description": "Predge score 0-100; null while the scorer has not graded this wallet" }, "win_rate": { "type": "number", "description": "Realized win rate 0-1, resolved markets only" }, "decided_trades": { "type": "integer" }, "trades_count": { "type": "integer" }, "total_volume_usd": { "type": "number" }, "avg_position_usd": { "type": "number" } } } } }, "required": [ "window", "min_trades", "insufficient_data" ] }, "example": { "window": "30d", "min_trades": 10, "insufficient_data": false, "wallets": [ { "address": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "score": 81, "win_rate": 0.71, "decided_trades": 17, "trades_count": 24, "total_volume_usd": 412000, "avg_position_usd": 17166.67 } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/wallets/{address}": { "get": { "operationId": "getWalletProfile", "tags": [ "wallets" ], "summary": "Wallet profile", "description": "Full profile of one Polymarket wallet. Returns Predge score (0-100), win rates (live-computed 7d/30d from resolved markets + scorer's 30d/90d), all-time totals (trades, PnL, avg position), top-5 favorite market categories, and the last 20 trades delayed 15 minutes. 404 (not charged) for wallets unknown to the Predge dataset.", "x-x402": { "priceUSD": "0.01", "amountAtomic": "10000" }, "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Polymarket proxy-wallet address (0x…, lowercase)", "schema": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" } } ], "responses": { "200": { "description": "Paid response with the wallet profile.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "found": { "type": "boolean" }, "score": { "type": [ "integer", "null" ], "description": "Predge score 0-100; null while unscored" }, "score_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "win_rate": { "type": "object", "properties": { "7d": { "type": [ "number", "null" ], "description": "Live-computed from resolved markets, last 7d" }, "30d": { "type": [ "number", "null" ], "description": "Live-computed from resolved markets, last 30d" }, "scorer_30d": { "type": [ "number", "null" ] }, "scorer_90d": { "type": [ "number", "null" ] } } }, "outcome_verified": { "type": "object", "description": "Which fields are verified against real market outcomes. win_rate is computed from resolved markets (true); pnl is a modeled proxy, not settled (false).", "properties": { "win_rate": { "type": "boolean" }, "pnl": { "type": "boolean" } } }, "note": { "type": "string", "description": "Clarifies that modeled_pnl_* is a MODELED signed-volume proxy, not realized/settled P&L." }, "totals": { "type": "object", "properties": { "trades_all_time": { "type": "integer" }, "modeled_pnl_30d_usd": { "type": "number", "description": "MODELED signed-volume proxy (30d) from the scorer, NOT realized/settled P&L" }, "modeled_pnl_all_time_usd": { "type": "number", "description": "MODELED signed-volume proxy (all-time) from the scorer, NOT realized/settled P&L" }, "avg_position_usd": { "type": "number" }, "first_seen_at": { "type": "string", "format": "date-time" } } }, "favorite_categories": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "category": { "type": "string" }, "trades": { "type": "integer" }, "volume_usd": { "type": "number" } } } }, "recent_trades": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/Trade" } } }, "required": [ "address", "found" ] }, "example": { "address": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "found": true, "score": 81, "score_updated_at": "2026-07-18T00:00:04.000Z", "outcome_verified": { "win_rate": true, "pnl": false }, "note": "modeled_pnl_* is a MODELED signed-volume proxy from the Predge scorer (+size on wins, −size on losses over resolved markets), NOT realized/settled P&L.", "win_rate": { "7d": 0.67, "30d": 0.71, "scorer_30d": 0.7, "scorer_90d": 0.64 }, "totals": { "trades_all_time": 214, "modeled_pnl_30d_usd": 48100.5, "modeled_pnl_all_time_usd": 302400, "avg_position_usd": 12800, "first_seen_at": "2026-05-02T10:11:00.000Z" }, "favorite_categories": [ { "category": "economics", "trades": 88, "volume_usd": 1204000 } ], "recent_trades": [ { "platform": "polymarket", "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "market_title": "Will the Fed cut rates in September?", "market_slug": "fed-rate-cut-september", "category": "economics", "side": "yes", "price": 0.62, "size_usd": 25400, "wallet": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "wallet_score": 81, "wallet_win_rate_30d": 0.67, "tx_hash": "0x6a7de5…", "block_timestamp": "2026-07-17T09:41:02.000Z" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "description": "Wallet unknown to the Predge dataset. NOT charged — the x402 middleware settles only after a successful handler response." } } } }, "/v1/wallets/{address}/history": { "get": { "operationId": "getWalletHistory", "tags": [ "wallets" ], "summary": "Wallet trade history + PnL curve", "description": "Historical trades for one wallet plus a running win-rate & MODELED-PnL curve, computed ONLY from resolved markets (modeled_pnl_usd assumes a $1 binary payout per winning share; shares = size_usd ÷ entry price — NOT realized/settled P&L). Unresolved trades still appear (won: null, modeled_pnl_usd: null) but do not move the curve. Up to 500 trades, most-recent-first, 15 min delay. 404 (not charged) for wallets unknown to the Predge dataset. outcome_verified: {win_rate: true, pnl: false}.", "x-x402": { "priceUSD": "0.02", "amountAtomic": "20000" }, "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Polymarket proxy-wallet address (0x…, lowercase)", "schema": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" } }, { "name": "window", "in": "query", "required": false, "description": "Lookback window (default 30d)", "schema": { "type": "string", "enum": [ "30d", "90d", "all" ], "default": "30d" } } ], "responses": { "200": { "description": "Paid response with the wallet trade history.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "found": { "type": "boolean" }, "window": { "type": "string" }, "outcome_verified": { "type": "object", "properties": { "win_rate": { "type": "boolean" }, "pnl": { "type": "boolean" } } }, "note": { "type": "string" }, "summary": { "type": "object", "properties": { "resolved_trades": { "type": "integer" }, "win_rate": { "type": [ "number", "null" ] }, "modeled_pnl_usd": { "type": [ "number", "null" ] } } }, "trades": { "type": "array", "maxItems": 500, "items": { "type": "object", "properties": { "condition_id": { "type": "string" }, "side": { "type": "string" }, "size_usd": { "type": "number" }, "entry_price": { "type": "number" }, "won": { "type": [ "boolean", "null" ] }, "modeled_pnl_usd": { "type": [ "number", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "required": [ "address", "found" ] }, "example": { "address": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "found": true, "window": "30d", "outcome_verified": { "win_rate": true, "pnl": false }, "note": "modeled_pnl_usd assumes a $1 binary payout per winning share (shares = size_usd ÷ entry price); NOT realized/settled P&L.", "summary": { "resolved_trades": 17, "win_rate": 0.71, "modeled_pnl_usd": 48100.5 }, "trades": [ { "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "side": "yes", "size_usd": 22000, "entry_price": 0.44, "won": true, "modeled_pnl_usd": 28000, "resolved_at": "2026-07-19T00:00:00.000Z" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "description": "Wallet unknown to the Predge dataset. NOT charged." } } } }, "/v1/wallets/compare": { "get": { "operationId": "compareWallets", "tags": [ "wallets" ], "summary": "Compare 2-10 wallets", "description": "Side-by-side comparison of 2-10 wallets. Each wallet: Predge score, live win_rate_7d/win_rate_30d (resolved markets only — outcome_verified: {win_rate: true, pnl: false}), modeled_pnl_30d_usd/modeled_pnl_all_time_usd (a MODELED signed-volume proxy from the scorer, NOT realized/settled P&L), and top-5 favorite categories; plus market_overlap: markets traded by >= 2 of the compared wallets. Wallets unknown to the dataset are returned with found:false rather than dropped.", "x-x402": { "priceUSD": "0.02", "amountAtomic": "20000" }, "parameters": [ { "name": "addresses", "in": "query", "required": true, "description": "Comma-separated 0x… addresses, 2-10 (deduplicated)", "schema": { "type": "string", "example": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8,0x1234567890123456789012345678901234567890" } } ], "responses": { "200": { "description": "Paid response with the wallet comparison.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome_verified": { "type": "object", "properties": { "win_rate": { "type": "boolean" }, "pnl": { "type": "boolean" } } }, "wallets": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "object", "properties": { "address": { "type": "string" }, "found": { "type": "boolean" }, "score": { "type": [ "integer", "null" ] }, "win_rate_7d": { "type": [ "number", "null" ] }, "win_rate_30d": { "type": [ "number", "null" ] }, "modeled_pnl_30d_usd": { "type": [ "number", "null" ] }, "modeled_pnl_all_time_usd": { "type": [ "number", "null" ] }, "favorite_categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "address", "found" ] } }, "market_overlap": { "type": "array", "items": { "type": "object", "properties": { "condition_id": { "type": "string" }, "title": { "type": "string" }, "wallets": { "type": "integer" } } } } }, "required": [ "wallets" ] }, "example": { "outcome_verified": { "win_rate": true, "pnl": false }, "wallets": [ { "address": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "found": true, "score": 81, "win_rate_7d": 0.67, "win_rate_30d": 0.71, "modeled_pnl_30d_usd": 48100.5, "modeled_pnl_all_time_usd": 302400, "favorite_categories": [ "economics", "politics" ] }, { "address": "0x1234567890123456789012345678901234567890", "found": false } ], "market_overlap": [ { "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "title": "Will the Fed cut rates in September?", "wallets": 2 } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/markets/movers": { "get": { "operationId": "getMarketMovers", "tags": [ "markets" ], "summary": "Largest YES-price moves", "description": "Largest YES-price moves across active Polymarket markets over a 1h/6h/24h window (15 min delay). Prices are derived from stored trade prints normalized to the YES side (NO prints count as 1 - price) — trade-print series, not orderbook quotes; markets need >= 2 prints in the window. Top-20 by |delta|.", "x-x402": { "priceUSD": "0.005", "amountAtomic": "5000" }, "parameters": [ { "name": "window", "in": "query", "required": false, "description": "Move window (default 6h)", "schema": { "type": "string", "enum": [ "1h", "6h", "24h" ], "default": "6h" } } ], "responses": { "200": { "description": "Paid response with the top price moves (or an honest insufficient_data envelope; both are charged).", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "1h", "6h", "24h" ] }, "insufficient_data": { "type": "boolean" }, "reason": { "type": "string", "description": "Present when insufficient_data is true" }, "note": { "type": "string" }, "markets": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "condition_id": { "type": "string" }, "platform": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "price_before": { "type": "number" }, "price_now": { "type": "number" }, "delta": { "type": "number", "description": "price_now - price_before (YES side)" }, "prints_in_window": { "type": "integer" }, "volume_in_window_usd": { "type": "number" }, "whale_volume_in_window_usd": { "type": "number", "description": "Volume from trades >= $10,000" } } } } }, "required": [ "window", "insufficient_data" ] }, "example": { "window": "6h", "insufficient_data": false, "note": "prices derived from trade prints normalized to the YES side, not orderbook quotes", "markets": [ { "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "platform": "polymarket", "title": "Will the Fed cut rates in September?", "category": "economics", "price_before": 0.44, "price_now": 0.62, "delta": 0.18, "prints_in_window": 9, "volume_in_window_usd": 96400, "whale_volume_in_window_usd": 71000 } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/markets/{conditionId}/history": { "get": { "operationId": "getMarketHistory", "tags": [ "markets" ], "summary": "Market price/volume history", "description": "Price/volume history for one Polymarket market. Trade-print price series in daily buckets (price normalized to the YES side, NOT orderbook quotes — outcome_verified.flow: false) with per-bucket volume and whale volume, plus up to 200 individual prints; includes resolution/resolved_at straight off the markets row when settled (outcome_verified.resolution: true). 15 min delay. 404 (not charged) if unknown.", "x-x402": { "priceUSD": "0.01", "amountAtomic": "10000" }, "parameters": [ { "name": "conditionId", "in": "path", "required": true, "description": "Polymarket condition id (0x…, 32-byte hex)", "schema": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, { "name": "window", "in": "query", "required": false, "description": "Lookback window (default 30d)", "schema": { "type": "string", "enum": [ "7d", "30d", "all" ], "default": "30d" } } ], "responses": { "200": { "description": "Paid response with the market history.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "object", "properties": { "condition_id": { "type": "string" }, "title": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "resolution": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "window": { "type": "string" }, "outcome_verified": { "type": "object", "properties": { "flow": { "type": "boolean" }, "resolution": { "type": "boolean" } } }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "bucket_start": { "type": "string", "format": "date-time" }, "trades": { "type": "integer" }, "volume_usd": { "type": "number" }, "whale_volume_usd": { "type": "number" }, "avg_price": { "type": "number" } } } }, "trades": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/Trade" } } }, "required": [ "market", "buckets" ] }, "example": { "market": { "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "title": "Will the Fed cut rates in September?", "category": "economics", "status": "active", "resolution": null, "resolved_at": null }, "window": "30d", "outcome_verified": { "flow": false, "resolution": true }, "buckets": [ { "bucket_start": "2026-07-17T00:00:00.000Z", "trades": 9, "volume_usd": 96400, "whale_volume_usd": 71000, "avg_price": 0.58 } ], "trades": [] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "description": "Market unknown to the Predge dataset. NOT charged." } } } }, "/v1/signals/consensus": { "get": { "operationId": "getSmartMoneyConsensus", "tags": [ "signals" ], "summary": "Smart-money consensus (premium)", "description": "PREMIUM smart-money consensus. For every active Polymarket market with whale trades (>= $10,000) in the last 24h by wallets with Predge score > 70: their YES/NO volume split, net flow (USD), distinct smart-wallet count, and a direction verdict — \"yes\"/\"no\" when one side holds >= 55% of smart volume (>= 10% imbalance), else \"split\". Sorted by smart volume, top-50. Honest degradation via `{\"insufficient_data\": true, \"reason\": ...}` while the scorer has not graded enough wallets. 15 min delay.", "x-x402": { "priceUSD": "0.03", "amountAtomic": "30000" }, "responses": { "200": { "description": "Paid response with per-market smart-money consensus (or an honest insufficient_data envelope; both are charged).", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "window_hours": { "type": "integer" }, "smart_score_min": { "type": "integer" }, "scored_wallets_total": { "type": "integer" }, "insufficient_data": { "type": "boolean" }, "reason": { "type": "string", "description": "Present when insufficient_data is true" }, "markets": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "condition_id": { "type": "string" }, "platform": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "market_yes_price": { "type": "number" }, "smart_wallets": { "type": "integer" }, "smart_yes_usd": { "type": "number" }, "smart_no_usd": { "type": "number" }, "net_flow_usd": { "type": "number" }, "direction": { "type": "string", "enum": [ "yes", "no", "split" ] } } } } }, "required": [ "window_hours", "smart_score_min", "insufficient_data" ] }, "example": { "window_hours": 24, "smart_score_min": 70, "scored_wallets_total": 412, "insufficient_data": false, "markets": [ { "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "platform": "polymarket", "title": "Will the Fed cut rates in September?", "category": "economics", "market_yes_price": 0.62, "smart_wallets": 6, "smart_yes_usd": 184000, "smart_no_usd": 41000, "net_flow_usd": 143000, "direction": "yes" } ] } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/": { "get": { "operationId": "getServiceDescription", "tags": [ "meta" ], "summary": "Service self-description (free)", "description": "Free machine-readable self-description: protocol parameters, endpoint list with prices, payment instructions. Always reflects the live configuration — treat it as the source of truth.", "responses": { "200": { "description": "Service description.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "meta" ], "summary": "Health check (free)", "description": "Free service + database status.", "responses": { "200": { "description": "Service healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "db": { "type": "string" }, "uptime_s": { "type": "number" }, "network": { "type": "string" }, "facilitator": { "type": "string" } } }, "example": { "status": "ok", "db": "up", "uptime_s": 1760, "network": "eip155:8453", "facilitator": "https://facilitator.payai.network" } } } } } } } }, "components": { "schemas": { "Trade": { "type": "object", "description": "One normalized Polymarket whale trade.", "properties": { "platform": { "type": "string", "enum": [ "polymarket" ] }, "condition_id": { "type": "string", "description": "Polymarket condition id (0x… 32-byte hex)" }, "market_title": { "type": "string" }, "market_slug": { "type": "string" }, "category": { "type": "string" }, "side": { "type": "string", "enum": [ "yes", "no" ] }, "price": { "type": "number", "description": "Execution price of the taken side, 0-1" }, "size_usd": { "type": "number", "description": "Trade notional in USD" }, "wallet": { "type": "string", "description": "Trader proxy-wallet address (lowercase)" }, "wallet_score": { "type": [ "integer", "null" ], "description": "Predge score 0-100; null while unscored" }, "wallet_win_rate_30d": { "type": [ "number", "null" ], "description": "Realized 30d win rate, resolved markets only" }, "tx_hash": { "type": "string" }, "block_timestamp": { "type": "string", "format": "date-time" } }, "example": { "platform": "polymarket", "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39", "market_title": "Will the Fed cut rates in September?", "market_slug": "fed-rate-cut-september", "category": "economics", "side": "yes", "price": 0.62, "size_usd": 25400, "wallet": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8", "wallet_score": 81, "wallet_win_rate_30d": 0.67, "tx_hash": "0x6a7de5…", "block_timestamp": "2026-07-17T09:41:02.000Z" } } }, "headers": { "PaymentResponse": { "description": "Base64-encoded x402 v2 settle receipt (JSON), including the on-chain transaction hash of the USDC settlement. Present on successfully paid responses.", "schema": { "type": "string", "contentEncoding": "base64" } } }, "responses": { "PaymentRequired": { "description": "Payment required (x402 v2). The `PAYMENT-REQUIRED` response header carries base64-encoded JSON with the resource description and the exact payment requirements (`accepts`: scheme `exact`, network, atomic USDC amount, asset contract, payTo address, maxTimeoutSeconds) plus Bazaar discovery metadata (input schema, output example). Sign an EIP-3009 USDC authorization matching `accepts[0]` and retry the same request with the `PAYMENT-SIGNATURE` header — or let an x402 client (`@x402/fetch`, `npx x402-proxy`) handle the whole flow. Requesting a 402 costs nothing.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 PaymentRequired JSON: `{ x402Version, resource, accepts[], extensions.bazaar }`.", "schema": { "type": "string", "contentEncoding": "base64" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } } } } }