{"name":"Polynews Intelligence API","version":"v1","description":"Prediction market intelligence for autonomous trading agents. Powered by Grok AI analysis, Polymarket data, and smart money detection.","network":"eip155:8453","payment":{"protocol":"x402","version":2,"currency":"USDC","chains":["Base","Solana"],"networks":[{"scheme":"exact","network":"eip155:8453","payTo":"0x6ee49a7872844397Fb52870Cc07b308fFADC9427","chain":"Base","currency":"USDC"},{"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","payTo":"76xzzgua9K8985GqGMwB946zTFtHvjTd9MfGoTYfys3d","chain":"Solana","currency":"USDC"}],"description":"Paid endpoints return HTTP 402 with payment requirements. Pay with USDC on Base or Solana, then retry with PAYMENT-SIGNATURE (X-Payment alias supported)."},"tiers":{"free":"No payment required — market discovery and live prices","standard":"$0.001-$0.005 per request — market data, trade feeds, and price history","premium":"$0.05-$0.08 per request — Grok-powered AI analysis","alpha":"$0.01-$0.10 per request — arbitrage detection, smart money, wallet scoring, and combo endpoints"},"quickStart":{"description":"Most agents should start here. Pick a workflow based on your goal:","steps":["1. Call GET /api/v1/docs (this endpoint) to discover endpoints and workflows","2. Call GET /api/v1/supported-networks (free) for Base + Solana payment receivers and network IDs","3. Call GET /api/v1/markets (free) to get market IDs and questions","4. Pick a workflow below and follow its steps, or use a combo endpoint to save calls"]},"links":{"humanDocs":"https://polynews.news/docs","catalog":"https://polynews.news/.well-known/x402.json","supportedNetworks":"https://polynews.news/api/v1/supported-networks","openapi":"https://polynews.news/openapi.json"},"workflows":[{"name":"full-market-analysis","description":"Complete market intelligence: news context, smart money detection, and wallet profiling for a specific market","totalCost":"$0.12-$0.22","steps":[{"step":1,"endpoint":"/api/v1/markets","method":"GET","purpose":"Discover active markets with IDs, questions, and current odds","extractFields":["[].id","[].question","[].outcomePrices","[].category"]},{"step":2,"endpoint":"/api/v1/market-context","method":"POST","purpose":"Get Grok-powered news and X post analysis for the market","input":"{ marketId: <step1.id>, marketQuestion: <step1.question>, marketOdds: <step1.outcomePrices formatted>, outcomeName?: <specific outcome name for focused analysis> }","parallel":true,"note":"For multi-outcome markets: use marketOutcomes[].name for odds (e.g. 'Before March 31: 13%, Before April 30: 22%'). Optionally pass outcomeName to focus Grok on a specific outcome."},{"step":3,"endpoint":"/api/v1/smart-money","method":"POST","purpose":"Detect suspicious wallets and whale positions in the market","input":"{ marketId: <step1.id> }","extractFields":["topSuspiciousWallets[].fullAddress","topYesHolders[].fullAddress","topNoHolders[].fullAddress"],"parallel":true,"note":"Steps 2 and 3 can run in parallel"},{"step":4,"endpoint":"/api/v1/wallet","method":"POST","purpose":"Profile individual wallets for sharp score and trade history","input":"{ walletAddress: <step3.topSuspiciousWallets[].fullAddress> }","note":"Call once per wallet of interest (top 3-5 recommended). $0.02 each."}],"shortcut":"/api/v1/smart-money-deep — combines steps 3+4 in one $0.10 call (9% discount). /api/v1/market-deep — combines steps 2+3 in one $0.09 call (10% discount)."},{"name":"quick-market-intel","description":"News context + smart money in a single call — the fastest way to assess a market","totalCost":"$0.09","steps":[{"step":1,"endpoint":"/api/v1/markets","method":"GET","purpose":"Get market IDs and questions","extractFields":["[].id","[].question"]},{"step":2,"endpoint":"/api/v1/market-deep","method":"POST","purpose":"Combined Grok news analysis + smart money detection (runs in parallel internally)","input":"{ marketId: <step1.id>, marketQuestion: <step1.question> }"}]},{"name":"morning-portfolio-briefing","description":"Daily Grok-powered briefing across multiple markets — does NOT require an account or watchlist","totalCost":"$0.08","steps":[{"step":1,"endpoint":"/api/v1/markets","method":"GET","purpose":"Get market list to select which markets to brief on","extractFields":["[].id","[].question"]},{"step":2,"endpoint":"/api/v1/morning-briefing","method":"POST","purpose":"Generate Grok-powered briefing with X posts and news across your selected markets","input":"{ markets: [ {id: <step1.id>, question: <step1.question>}, ... ] }","note":"Pass an array of markets. No account or watchlist needed — just pick markets from step 1."}]},{"name":"arbitrage-scan","description":"Find cross-platform price discrepancies between Polymarket and Kalshi","totalCost":"$0.01","steps":[{"step":1,"endpoint":"/api/v1/arbitrage","method":"GET","purpose":"Scan for fee-adjusted arbitrage opportunities with spread and confidence data","note":"Optional params: ?minSpread=0.01&category=politics&limit=50"}]},{"name":"whale-tracking","description":"Monitor large trades in real-time and profile interesting wallets","totalCost":"$0.001-$0.021 per check","steps":[{"step":1,"endpoint":"/api/v1/feed","method":"GET","purpose":"Get recent large trades ($500+) with wallet addresses","extractFields":["trades[].wallet","trades[].market","trades[].amount"],"note":"Optional filters: ?wallet=0x...&marketId=...&since=<unix_timestamp>&minValue=500"},{"step":2,"endpoint":"/api/v1/wallet","method":"POST","purpose":"Profile wallets that made interesting trades","input":"{ walletAddress: <step1.trades[].wallet> }","note":"Optional — only call for wallets with large or suspicious trades."}]},{"name":"election-consensus","description":"Pick a candidate/party election market, then get a calibrated consensus forecast blending prediction-market odds with a synthesized polling average","totalCost":"$0.06","steps":[{"step":1,"endpoint":"/api/v1/markets","method":"GET","purpose":"Discover an election market; pick a candidate/party WINNER market and take its slug (or id)","note":"Free. Skip margin-of-victory, balance-of-power, binary YES/NO, seat-count, date, and turnout markets — they aren't candidate fields and the forecast rejects them."},{"step":2,"endpoint":"/api/v1/election-forecast","method":"GET","input":"?slug=<event slug> (or ?race=<registered key>)","purpose":"Get Grok-synthesized per-candidate probabilities with market/poll breakdown, the individual polls averaged into each candidate, and source citations","note":"Grounds the market component on live Polymarket odds. Errors (unsuitable market, timeout) are not charged."}]}],"endpoints":[{"path":"/api/v1/markets","method":"GET","tier":"free","price":"$0.00","description":"All active prediction markets with prices, volume, and categories","parameters":{},"dependencies":[],"example":{"request":null,"response":{"data":[{"id":"69317","question":"Will the US strike Iran by April 30?","outcomePrices":["0.25","0.75"],"outcomes":["Yes","No"],"volume":1250000,"category":"geopolitics","isMultiOutcome":false}]}}},{"path":"/api/v1/live-prices","method":"GET","tier":"free","price":"$0.00","description":"Current market prices and volumes by outcome","parameters":{"marketId":{"type":"string","required":true,"description":"Polymarket event ID or slug (e.g. '69317' or 'democratic-presidential-nominee-2028'). Get IDs from GET /api/v1/markets"}},"dependencies":[{"endpoint":"/api/v1/markets","field":"marketId","description":"Get marketId from the markets list"}],"example":null},{"path":"/api/v1/price-history","method":"GET","tier":"standard","price":"$0.005","description":"Historical price data with configurable timeframes (1H/6H/1D/1W/1M/ALL)","parameters":{"marketId":{"type":"string","required":true,"description":"Polymarket event ID or slug (e.g. '69317' or 'democratic-presidential-nominee-2028'). Get IDs from GET /api/v1/markets"},"range":{"type":"string","required":false,"description":"Time range: 1H, 6H, 1D, 1W, 1M, ALL (default: 1D)"}},"dependencies":[{"endpoint":"/api/v1/markets","field":"marketId","description":"Get marketId from the markets list"}],"example":null},{"path":"/api/v1/feed","method":"GET","tier":"standard","price":"$0.001","description":"Real-time trade stream with market summaries (2hr rolling window, $500+ trades)","parameters":{"since":{"type":"number","required":false,"description":"Unix timestamp to fetch trades from (default: 30min ago)"},"marketId":{"type":"string","required":false,"description":"Filter by Polymarket event ID or slug (e.g. '69317' or 'democratic-presidential-nominee-2028')"},"wallet":{"type":"string","required":false,"description":"Filter by wallet address"},"minValue":{"type":"number","required":false,"description":"Minimum trade value in USD (default: 500)"},"limit":{"type":"number","required":false,"description":"Max trades to return (default: 100, max: 500)"}},"dependencies":[],"example":{"request":null,"response":{"data":{"trades":[{"wallet":"0xabc...","market":"Iran Strikes","side":"YES","amount":5000,"timestamp":1707900000}],"summary":{"totalTrades":45,"totalVolume":234000}}}}},{"path":"/api/v1/market-info","method":"POST","tier":"standard","price":"$0.005","description":"Market structure metadata: type detection, available outcomes with probabilities","parameters":{"marketId":{"type":"string","required":true,"description":"Polymarket event ID or slug (e.g. '69317' or 'democratic-presidential-nominee-2028'). Get IDs from GET /api/v1/markets"}},"dependencies":[{"endpoint":"/api/v1/markets","field":"marketId","description":"Get marketId from the markets list"}],"example":null},{"path":"/api/v1/market-context","method":"POST","tier":"premium","price":"$0.05","description":"Grok-powered market analysis: ranked news + X citations with a structured summary (recent developments, background context, market interpretation, what to watch)","parameters":{"marketQuestion":{"type":"string","required":true,"description":"The market question text"},"marketId":{"type":"string","required":true,"description":"Polymarket event ID or slug (e.g. '69317' or 'democratic-presidential-nominee-2028'). Get IDs from GET /api/v1/markets"},"marketOdds":{"type":"string","required":false,"description":"Current market odds for context"},"customXSources":{"type":"string[]","required":false,"description":"Custom X accounts to prioritize"},"outcomeName":{"type":"string","required":false,"description":"For multi-outcome markets: focus analysis on a specific outcome (e.g. 'Before April 30'). Omit for overall market analysis."}},"dependencies":[{"endpoint":"/api/v1/markets","field":"marketId, marketQuestion","description":"Get marketId and question text from the markets list"}],"example":{"request":{"marketId":"69317","marketQuestion":"Will the US strike Iran by April 30?","marketOdds":"Before March 31: 13%, Before April 30: 22%, Before June 30: 35%","outcomeName":"Before April 30"},"response":{"data":{"items":[{"title":"Reuters: US deploys carrier group","url":"https://...","source":"Reuters","type":"news"},{"title":"@sentdefender: Major military movement","url":"https://x.com/...","source":"@sentdefender","type":"x_post"}],"summary":"**Recent Developments (48h):** ... **Context:** ... **Market Interpretation:** ... **What To Watch:** ...","cached":false,"_note":"For multi-outcome markets: pass all outcome odds in marketOdds and optionally set outcomeName to focus analysis on a specific outcome. Omit outcomeName for overall market analysis."}}}},{"path":"/api/v1/analyze-move","method":"POST","tier":"premium","price":"$0.05","description":"Grok-powered price movement catalyst analysis with confidence scoring. Simplest usage: pass just { marketId } and we resolve the market, pull price history, and analyze its most significant recent move. Advanced callers may instead supply a full { move, marketQuestion, outcomeName } payload.","parameters":{"marketId":{"type":"string","required":false,"description":"Polymarket event ID or slug (e.g. '69317' or 'democratic-presidential-nominee-2028'). When provided, the move is detected server-side — no need to build a MarketMove. Get IDs from GET /api/v1/markets"},"outcomeName":{"type":"string","required":false,"description":"Optional with marketId: focus on a specific outcome (e.g. 'Newsom'). Required only when supplying a full move payload."},"range":{"type":"string","required":false,"description":"With marketId: detection window — 1H, 6H, 1D, 1W, 1M, ALL (default: 1W)"},"move":{"type":"MarketMove","required":false,"description":"Advanced: explicit price movement data. Omit when using marketId."},"marketQuestion":{"type":"string","required":false,"description":"Advanced: market question text. Required only with an explicit move payload."},"nearbyNews":{"type":"ContextItem[]","required":false,"description":"Optional news items near the move to improve catalyst attribution"}},"dependencies":[{"endpoint":"/api/v1/markets","field":"id (or slug)","description":"Get marketId or slug. Pass as marketId for automatic server-side move detection (no need to pre-build MarketMove or call price-history)."},{"endpoint":"/api/v1/move-context","field":"nearbyNews (optional)","description":"Optional richer news/X context around the move. The lightweight {marketId} path works without it; supply via move-context or market-context only if you want custom attribution."}],"example":{"request":{"marketId":"69317"},"response":{"data":{"summary":"Reuters report at 14:23 EST confirming a senior Newsom advisor will join the 2028 exploratory committee triggered the sharp +5pt rally over the next 15 minutes.","catalysts":[{"newsTitle":"Reuters: Newsom advisor joins 2028 exploratory committee","newsUrl":"https://reuters.com/...","likelihood":5,"reasoning":"Wire published minutes before the price inflection on the Newsom outcome; volume 4x spike and direct positive development for the candidate."}],"confidence":4,"_note":"Simplest usage (new auto mode): pass only { marketId } (event ID or slug from /markets). Server resolves the market, detects the most significant recent move via CLOB price history, and runs Grok catalyst analysis. Optional: outcomeName, range (1W default), nearbyNews (from move-context). Full legacy payload still accepted."}}}},{"path":"/api/v1/move-context","method":"POST","tier":"premium","price":"$0.05","description":"Search for news and X posts around a specific price movement timestamp","parameters":{"marketQuestion":{"type":"string","required":true,"description":"The market question text"},"moveTimestamp":{"type":"number","required":true,"description":"Unix timestamp of the price movement"},"windowHours":{"type":"number","required":false,"description":"Hours before/after to search (default: 24)"}},"dependencies":[{"endpoint":"/api/v1/price-history","field":"moveTimestamp","description":"Identify timestamp of price movement to search around"}],"example":null},{"path":"/api/v1/morning-briefing","method":"POST","tier":"premium","price":"$0.08","description":"Grok-powered daily briefing across a set of markets you supply (no account or watchlist needed): headline, key developments, and sentiment","parameters":{"markets":{"type":"Array<{question, id, odds}>","required":true,"description":"Array of markets to include in briefing"}},"dependencies":[{"endpoint":"/api/v1/markets","field":"markets array","description":"Build markets array [{id, question}] from the markets list. No watchlist/account needed."}],"example":{"request":{"markets":[{"id":"69317","question":"Will the US strike Iran by April 30?"},{"id":"31875","question":"Republican Presidential Nominee 2028"}]},"response":{"data":{"headline":"Iran Tensions Dominate as 2028 Race Heats Up","summary":"Military posturing in the Middle East...","sentiment":"bearish","keyDevelopments":[{"title":"Pentagon Briefing Signals Escalation","sentiment":"negative","sources":[]}]}}}},{"path":"/api/v1/election-forecast","method":"GET","tier":"premium","price":"$0.06","description":"Grok-synthesized consensus forecast for candidate/party WINNER election markets (US and international). Blends live Polymarket odds (ground truth) with a polling average Grok synthesizes from multiple sources via web_search; returns per-candidate composites (equal-weight market+poll), the individual polls averaged into each candidate (verifiable), and cited sources. Target a market with a registered 'race' key or any Polymarket election event 'slug'.","parameters":{"race":{"type":"string","required":false,"description":"Registered race key, e.g. 'dem-nominee-2028', 'gop-nominee-2028', 'ca-governor-2026', 'oh-senate-2026', 'pres-winner-2028', 'senate-2026-control'. Full list in lib/election-races.ts."},"slug":{"type":"string","required":false,"description":"Polymarket event slug for any other (e.g. international) election market, e.g. 'next-french-presidential-election'. Provide either 'race' or 'slug'; one is required."}},"appliesTo":"Candidate/party WINNER markets only: outcomes must be a field of candidates or parties (nominee, president, governor, party-control, etc.). NOT supported (returns 500 FORECAST_ERROR; a Grok timeout returns 504 GROK_TIMEOUT; you are NOT charged for any error response): margin-of-victory, vote-share, balance-of-power / multi-chamber scenarios, binary YES/NO ('will X pass?'), seat-count ('how many seats'), date ('election called by when?'), and turnout markets. The caller selects the market: use GET /api/v1/markets to discover candidate-field election markets.","dependencies":[{"endpoint":"/api/v1/markets","field":"slug (or id)","description":"Discover an election market and pass its slug as ?slug= (or use a registered ?race= key). Must be a candidate/party WINNER market — see the endpoint's appliesTo for which market types are rejected."}],"example":{"request":null,"response":{"data":{"race":"2028 Democratic Presidential Nominee","candidates":[{"name":"Gavin Newsom","composite":0.24,"components":{"market":0.21,"poll":0.27},"polls":[{"pollster":"Morning Consult (Dem primary)","value":0.29,"date":"2026-05-18","url":"https://example.com/poll"},{"pollster":"Emerson College","value":0.25,"date":"2026-05-10"}]},{"name":"Pete Buttigieg","composite":0.16,"components":{"market":0.18,"poll":0.16}}],"weights":{"market":0.5,"poll":0.5},"sentiment":"neutral","summary":"Newsom holds a narrow front-runner edge as the field stays fragmented.","sources":[{"label":"270toWin poll average","url":"https://www.270towin.com/2028-democratic-nomination/"}],"lastUpdated":"2026-05-23T04:30:00.000Z","mode":"grok"}}}},{"path":"/api/v1/wallet","method":"POST","tier":"alpha","price":"$0.02","description":"Wallet performance scoring: sharp score, trader badge, top trades, and calibration metrics (alpha/Brier/conviction)","parameters":{"walletAddress":{"type":"string","required":true,"description":"Polymarket wallet address"}},"dependencies":[{"endpoint":"/api/v1/smart-money","field":"walletAddress","description":"Get wallet addresses from topSuspiciousWallets[].fullAddress, topYesHolders[].fullAddress, or topNoHolders[].fullAddress"}],"example":{"request":{"walletAddress":"0x1a2b3c4d5e6f..."},"response":{"data":{"address":"0x1a2b3c4d5e6f...","sharpScore":85,"badge":"Proven Winner","metrics":{"alphaScore":72,"brierScore":65,"convictionScore":58},"topTrades":[{"market":"Will Trump win 2024?","profit":15000,"outcome":"Yes"}]}}}},{"path":"/api/v1/smart-money","method":"POST","tier":"alpha","price":"$0.05","description":"Smart money detection: suspicious wallets, top YES/NO holders, sentiment direction, insider signal counts, and a trade recommendation","parameters":{"marketId":{"type":"string","required":true,"description":"Polymarket event ID or slug (e.g. '69317' or 'democratic-presidential-nominee-2028'). Get IDs from GET /api/v1/markets"},"conditionId":{"type":"string","required":false,"description":"Specific outcome condition ID for multi-outcome markets"}},"dependencies":[{"endpoint":"/api/v1/markets","field":"marketId","description":"Get marketId from the markets list"}],"example":{"request":{"marketId":"69317"},"response":{"data":{"analysis":{"overallScore":72,"totalTradesAnalyzed":156},"topSuspiciousWallets":[{"address":"0x1a2b...3c4d","fullAddress":"0x1a2b3c4d5e6f...","amount":45000,"largestTrade":25000}],"topYesHolders":[{"address":"0xaa11...bb22","fullAddress":"0xaa11bb22cc33...","positionValue":120000}],"topNoHolders":[{"address":"0xdd44...ee55","fullAddress":"0xdd44ee55ff66...","positionValue":95000}],"recommendation":{"action":"CAUTION","reason":"Unusual concentration in YES positions"}}}}},{"path":"/api/v1/arbitrage","method":"GET","tier":"alpha","price":"$0.01","description":"Cross-platform arbitrage detection between Polymarket and Kalshi: matched markets, price spreads, fee-adjusted EV. Coverage: liquid Polymarket markets in politics/geopolitics/elections/tech/economy/finance; low-volume long-tail, sports, culture, and weather are not included.","parameters":{"minSpread":{"type":"number","required":false,"description":"Minimum raw price spread to include (default: 0.01)"},"category":{"type":"string","required":false,"description":"Filter by Polymarket category: politics, geopolitics, elections, tech, economy, finance (liquid markets only)"},"limit":{"type":"number","required":false,"description":"Max opportunities to return (default: 50, max: 100)"}},"dependencies":[],"example":null},{"path":"/api/v1/smart-money-deep","method":"POST","tier":"alpha","price":"$0.10","description":"Smart money analysis + auto-profiles top N suspicious/notable wallets in one call. 9% cheaper than calling smart-money + wallet individually.","parameters":{"marketId":{"type":"string","required":true,"description":"Polymarket event ID or slug. Get IDs from GET /api/v1/markets"},"conditionId":{"type":"string","required":false,"description":"Specific outcome condition ID for multi-outcome markets"},"topN":{"type":"number","required":false,"description":"Number of wallets to auto-profile (default: 3, max: 5). Picks suspicious wallets first, then top holders."}},"dependencies":[{"endpoint":"/api/v1/markets","field":"marketId","description":"Get marketId from the markets list"}],"example":{"request":{"marketId":"69317","topN":3},"response":{"data":{"smartMoney":{"analysis":{"overallScore":72},"topSuspiciousWallets":[],"topYesHolders":[],"topNoHolders":[]},"walletProfiles":[{"address":"0x1a2b...","sharpScore":85,"badge":"Proven Winner"}],"walletsProfiled":3,"topN":3}}}},{"path":"/api/v1/market-deep","method":"POST","tier":"alpha","price":"$0.09","description":"Grok-powered news/X analysis + smart money detection in one parallel call. 10% cheaper than calling market-context + smart-money individually.","parameters":{"marketId":{"type":"string","required":true,"description":"Polymarket event ID or slug. Get IDs from GET /api/v1/markets"},"marketQuestion":{"type":"string","required":true,"description":"The market question text (from /api/v1/markets response)"},"marketOdds":{"type":"string","required":false,"description":"Current market odds for Grok context (e.g. 'Yes: 25%, No: 75%')"},"conditionId":{"type":"string","required":false,"description":"Specific outcome condition ID for multi-outcome markets"},"outcomeName":{"type":"string","required":false,"description":"For multi-outcome markets: focus analysis on a specific outcome (e.g. 'Before April 30'). Omit for overall market analysis."}},"dependencies":[{"endpoint":"/api/v1/markets","field":"marketId, marketQuestion","description":"Get marketId and question text from the markets list"}],"example":{"request":{"marketId":"69317","marketQuestion":"Will the US strike Iran by April 30?","outcomeName":"Before April 30"},"response":{"data":{"marketContext":{"items":[],"summary":"...","cached":false},"smartMoney":{"analysis":{"overallScore":72},"topSuspiciousWallets":[],"recommendation":{}},"_note":"outcomeName is optional — omit for overall market analysis. For multi-outcome markets, use marketOutcomes[].name from GET /api/v1/markets."}}}}]}