{ "openapi": "3.1.0", "info": { "title": "ProudGlobeHead Markets API", "version": "1.0.0", "summary": "Prediction markets, explained by the money.", "description": "Track what is moving, where prediction markets disagree, what the largest traders are doing, and what public conversation is moving alongside them.\n\nMarket data is normalized from Kalshi and Polymarket public APIs. Probabilities are 0..1. Movement is expressed in percentage points. Free endpoints return the same data the website renders; paid endpoints add depth (complete feeds, evidence packages, depth simulation) and are settled per request over x402.\n\nThis is informational analytics, not financial advice.", "contact": { "name": "ProudGlobeHead Markets Desk", "url": "https://proudglobehead.com/markets/methodology" } }, "servers": [ { "url": "https://proudglobehead.com" } ], "tags": [ { "name": "Overview" }, { "name": "Markets" }, { "name": "Movement" }, { "name": "Trades" }, { "name": "Gaps" }, { "name": "Briefing" }, { "name": "Search" }, { "name": "Paid", "description": "Settled in USDC on Base using x402." }, { "name": "Status" } ], "paths": { "/markets/api/health": { "get": { "summary": "Service health and upstream freshness", "tags": [ "Status" ], "responses": { "200": { "description": "Health snapshot.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/overview": { "get": { "summary": "Homepage intelligence: statistics, lead card, top movers, gaps and trades", "tags": [ "Overview" ], "responses": { "200": { "description": "Current intelligence state.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "The first refresh has not completed.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/markets": { "get": { "summary": "Browse normalized markets from both venues", "tags": [ "Markets" ], "parameters": [ { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "kalshi", "polymarket" ] } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "settled" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "significance", "absolute", "volume", "liquidity", "flow" ] }, "description": "Ranking used to order results." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Maximum rows returned." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated market list with live quotes.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/markets/{id}": { "get": { "summary": "Full intelligence for one market", "tags": [ "Markets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market id, for example k:TICKER or p:12345." }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "1H", "6H", "24H", "7D", "ALL" ] }, "description": "History range." } ], "responses": { "200": { "description": "Market record, quote, history, trades, explanation and timeline.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown market.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/markets/{id}/series": { "get": { "summary": "Probability history for one market", "tags": [ "Markets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "1H", "6H", "24H", "7D", "ALL" ] }, "description": "History range." } ], "responses": { "200": { "description": "Array of [unix_seconds, probability] pairs.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/movers": { "get": { "summary": "Top movers on both venues", "tags": [ "Movement" ], "parameters": [ { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "1h", "6h", "24h", "7d" ] }, "description": "Movement window." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "significance", "absolute", "volume", "liquidity", "flow" ] }, "description": "Ranking used to order results." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Maximum rows returned." } ], "responses": { "200": { "description": "Ranked movers.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/movers/kalshi": { "get": { "summary": "Top Kalshi movers", "tags": [ "Movement" ], "parameters": [ { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "1h", "6h", "24h", "7d" ] }, "description": "Movement window." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "significance", "absolute", "volume", "liquidity", "flow" ] }, "description": "Ranking used to order results." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Maximum rows returned." } ], "responses": { "200": { "description": "Ranked Kalshi movers.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/movers/polymarket": { "get": { "summary": "Top Polymarket movers", "tags": [ "Movement" ], "parameters": [ { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "1h", "6h", "24h", "7d" ] }, "description": "Movement window." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "significance", "absolute", "volume", "liquidity", "flow" ] }, "description": "Ranking used to order results." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Maximum rows returned." } ], "responses": { "200": { "description": "Ranked Polymarket movers.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/trades": { "get": { "summary": "Largest and most impactful trades on both venues", "tags": [ "Trades" ], "responses": { "200": { "description": "Trade boards for 1h and 24h windows.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/trades/{platform}": { "get": { "summary": "Trade board for one venue", "tags": [ "Trades" ], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "kalshi", "polymarket" ] } } ], "responses": { "200": { "description": "Trade board.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/gaps": { "get": { "summary": "Cross-venue discrepancy board", "tags": [ "Gaps" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Maximum rows returned." } ], "responses": { "200": { "description": "Matched pairs with probability gaps and lead/lag events.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/pairs/{id}": { "get": { "summary": "Matched pair detail", "tags": [ "Gaps" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pair id or slug." }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "1H", "6H", "24H", "7D", "ALL" ] }, "description": "History range." } ], "responses": { "200": { "description": "Pair with both sides, gap history and theoretical edge summary.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/pairs/{id}/series": { "get": { "summary": "Both venues plus gap history for a pair", "tags": [ "Gaps" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "1H", "6H", "24H", "7D", "ALL" ] }, "description": "History range." } ], "responses": { "200": { "description": "Series for both venues and the gap.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/briefing/latest": { "get": { "summary": "Most recent morning briefing", "tags": [ "Briefing" ], "responses": { "200": { "description": "Briefing content and evidence hash.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/briefing/{date}": { "get": { "summary": "Morning briefing for one New York date", "tags": [ "Briefing" ], "parameters": [ { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Briefing content.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No briefing for that date.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/briefings": { "get": { "summary": "Briefing archive index", "tags": [ "Briefing" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Maximum rows returned." } ], "responses": { "200": { "description": "Archive list.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/search": { "get": { "summary": "Search markets and matched pairs", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Maximum rows returned." } ], "responses": { "200": { "description": "Grouped search results.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets/api/pro/what-is-moving": { "get": { "summary": "Ranked cross-venue movement with significance and flow context", "description": "Every qualifying mover on both venues for the 1h, 6h, 24h and 7d windows, with movement significance, trade acceleration, the largest trade in the window and the matched contract on the other venue. Updated every 5 minutes. Paid: 0.10 USDC on Base via x402.", "tags": [ "Paid" ], "parameters": [], "responses": { "200": { "description": "Paid response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated_at": { "type": "integer", "description": "Unix seconds" }, "windows": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/MoverEntry" } } } } } } } }, "402": { "description": "Payment required. The response carries x402 payment requirements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "product": { "type": "string" }, "price_usdc": { "type": "number" }, "network": { "type": "string" }, "asset": { "type": "string" }, "free_alternative": { "type": "string" } } } } } } }, "x-402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": "0.10", "payTo": "0x3eAf0c6Ece232A3BCB7f57E91C2e829eCE676532", "facilitator": "https://facilitator.payai.network", "example_use": "Rank the strongest prediction-market moves of the last hour and tell me which are corroborated by trade flow." } } }, "/markets/api/pro/full-gap-feed": { "get": { "summary": "Complete Kalshi/Polymarket discrepancy board", "description": "All active matched pairs with both probabilities, the signed and absolute gap, liquidity-weighted gap, historical percentile, movement lead/lag, match grade and theoretical edge where the pair qualifies. Updated every 5 minutes. Paid: 0.20 USDC on Base via x402.", "tags": [ "Paid" ], "parameters": [], "responses": { "200": { "description": "Paid response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/GapEntry" } } } } } } }, "402": { "description": "Payment required. The response carries x402 payment requirements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "product": { "type": "string" }, "price_usdc": { "type": "number" }, "network": { "type": "string" }, "asset": { "type": "string" }, "free_alternative": { "type": "string" } } } } } } }, "x-402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": "0.20", "payTo": "0x3eAf0c6Ece232A3BCB7f57E91C2e829eCE676532", "facilitator": "https://facilitator.payai.network", "example_use": "Find every event where the two venues disagree by more than four points with real liquidity on both sides." } } }, "/markets/api/pro/pair/{id}": { "get": { "summary": "Deep matched-pair intelligence", "description": "Full pair record including deterministic component scores, hard conflicts, semantic verifier output, outcome mapping, gap history, order-book depth simulation at six budgets, risk flags and the generated explanation. Updated every 5 minutes; matching re-verified hourly. Paid: 0.25 USDC on Base via x402.", "tags": [ "Paid" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pair": { "type": "object" }, "arbitrage": { "type": "object" }, "gap_history": { "type": "array" } } } } } }, "402": { "description": "Payment required. The response carries x402 payment requirements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "product": { "type": "string" }, "price_usdc": { "type": "number" }, "network": { "type": "string" }, "asset": { "type": "string" }, "free_alternative": { "type": "string" } } } } } } }, "x-402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": "0.25", "payTo": "0x3eAf0c6Ece232A3BCB7f57E91C2e829eCE676532", "facilitator": "https://facilitator.payai.network", "example_use": "Explain whether the Kalshi and Polymarket contracts on this event really settle the same way." } } }, "/markets/api/pro/flow/{marketId}": { "get": { "summary": "Trade-flow analysis for one market", "description": "Recent trades with notional, block-trade flags, price before, price five minutes later, realised movement and impact score, plus the most price-impactful trades ranked separately from the largest. Updated every 5 minutes. Paid: 0.15 USDC on Base via x402.", "tags": [ "Paid" ], "parameters": [ { "name": "marketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "largest": { "type": "array" }, "most_impactful": { "type": "array" } } } } } }, "402": { "description": "Payment required. The response carries x402 payment requirements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "product": { "type": "string" }, "price_usdc": { "type": "number" }, "network": { "type": "string" }, "asset": { "type": "string" }, "free_alternative": { "type": "string" } } } } } } }, "x-402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": "0.15", "payTo": "0x3eAf0c6Ece232A3BCB7f57E91C2e829eCE676532", "facilitator": "https://facilitator.payai.network", "example_use": "Show me which trades actually moved this market rather than just the biggest ones." } } }, "/markets/api/pro/timeline/{marketId}": { "get": { "summary": "Reconstructed event timeline", "description": "Deterministic chronology of price moves, notable trades and cross-venue gap changes, each entry carrying an evidence id that the explanation endpoints reference. Updated every 5 minutes. Paid: 0.15 USDC on Base via x402.", "tags": [ "Paid" ], "parameters": [ { "name": "marketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } } } }, "402": { "description": "Payment required. The response carries x402 payment requirements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "product": { "type": "string" }, "price_usdc": { "type": "number" }, "network": { "type": "string" }, "asset": { "type": "string" }, "free_alternative": { "type": "string" } } } } } } }, "x-402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": "0.15", "payTo": "0x3eAf0c6Ece232A3BCB7f57E91C2e829eCE676532", "facilitator": "https://facilitator.payai.network", "example_use": "Give me the minute-by-minute sequence of what happened to this market this morning." } } }, "/markets/api/pro/morning": { "get": { "summary": "Complete morning briefing data package", "description": "The frozen evidence package behind today’s briefing: top movers and trades on both venues, discrepancies, Grade A opportunities, lead/lag events, the article content and the evidence hash. Updated daily at 08:00 America/New_York. Paid: 0.25 USDC on Base via x402.", "tags": [ "Paid" ], "parameters": [], "responses": { "200": { "description": "Paid response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence": { "type": "object" }, "article": { "type": "object" }, "evidence_hash": { "type": "string" } } } } } }, "402": { "description": "Payment required. The response carries x402 payment requirements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "product": { "type": "string" }, "price_usdc": { "type": "number" }, "network": { "type": "string" }, "asset": { "type": "string" }, "free_alternative": { "type": "string" } } } } } } }, "x-402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": "0.25", "payTo": "0x3eAf0c6Ece232A3BCB7f57E91C2e829eCE676532", "facilitator": "https://facilitator.payai.network", "example_use": "Fetch this morning’s prediction-market briefing with the underlying evidence rows." } } }, "/markets/api/pro/data-package/{marketId}": { "get": { "summary": "Complete data package for one market", "description": "Everything held for a market in one response: normalized record, quote, full snapshot history, order book, trades with impact, timeline, matched pair, arbitrage and explanation. Updated every 5 minutes. Paid: 0.25 USDC on Base via x402.", "tags": [ "Paid" ], "parameters": [ { "name": "marketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "object" }, "history": { "type": "array" } } } } } }, "402": { "description": "Payment required. The response carries x402 payment requirements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "product": { "type": "string" }, "price_usdc": { "type": "number" }, "network": { "type": "string" }, "asset": { "type": "string" }, "free_alternative": { "type": "string" } } } } } } }, "x-402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": "0.25", "payTo": "0x3eAf0c6Ece232A3BCB7f57E91C2e829eCE676532", "facilitator": "https://facilitator.payai.network", "example_use": "Download the full intelligence record for this market in a single call." } } } }, "components": { "schemas": { "MoverEntry": { "type": "object", "properties": { "market_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "kalshi", "polymarket" ] }, "slug": { "type": "string" }, "title": { "type": "string" }, "probability": { "type": "number", "minimum": 0, "maximum": 1 }, "delta_pp": { "type": "number", "description": "Movement in percentage points." }, "significance": { "type": "number", "minimum": 0, "maximum": 100 }, "volume_24h": { "type": [ "number", "null" ] }, "liquidity": { "type": [ "number", "null" ] }, "largest_trade": { "type": [ "number", "null" ] }, "pair_slug": { "type": [ "string", "null" ] } } }, "GapEntry": { "type": "object", "properties": { "pair_id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "grade": { "type": "string", "enum": [ "A", "B", "C" ] }, "match_confidence": { "type": "number" }, "absolute_gap_pp": { "type": [ "number", "null" ] }, "liquidity_weighted_gap": { "type": [ "number", "null" ] }, "historical_percentile": { "type": [ "number", "null" ] }, "theoretical_edge_pct": { "type": [ "number", "null" ] } } }, "TimelineEvent": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix seconds." }, "kind": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "evidence_id": { "type": "string" } } } } } }