{"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":"base","payment":{"protocol":"x402","currency":"USDC","chain":"Base","description":"Paid endpoints return HTTP 402 with payment requirements. Submit payment on Base and retry with Payment-Signature header."},"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/markets (free) to get market IDs and questions","3. Pick a workflow below and follow its steps, or use a combo endpoint to save calls"]},"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."}]}],"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: breaking news, background context, forward signals, and source citations from news + X","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","parameters":{"move":{"type":"MarketMove","required":true,"description":"Price movement data (direction, magnitude, timestamps)"},"marketQuestion":{"type":"string","required":true,"description":"The market question text"},"outcomeName":{"type":"string","required":true,"description":"Outcome that moved"},"nearbyNews":{"type":"ContextItem[]","required":true,"description":"News items near the time of the move"}},"dependencies":[{"endpoint":"/api/v1/market-context","field":"nearbyNews","description":"Get news/X items from market-context to correlate with price moves"},{"endpoint":"/api/v1/price-history","field":"move data","description":"Identify price movements from historical data"}],"example":null},{"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 market briefing: headline, key developments, sentiment analysis across watchlist","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/wallet","method":"POST","tier":"alpha","price":"$0.02","description":"Wallet performance scoring: sharp score, badges, top trades, P&L metrics","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 wallet analysis, holder positions, sentiment, insider signals, trade recommendations","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","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"},"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."}}}}]}