{ "openapi": "3.1.0", "info": { "title": "Prediction Market Data API", "version": "2.0.0", "description": "Prediction Market Data API with x402 micropayment support, from Lukka. Pay per-call in USDC on Base mainnet.", "x-guidance": "All endpoints are GET-only and return JSON. Pay per-call via x402 (USDC on Base mainnet, eip155:8453) — no signup needed. Start with GET /prediction-markets to search events; use the returned `event_ticker` to call GET /prediction-markets/similar or GET /price-history (requires `exchangeId`: 4141=Kalshi, 4137=Polymarket, 4008=Gemini). Time-series endpoints (/market-overview, /open-interest, /prediction-total-volume) require `from`, `to` (ISO-8601 UTC), and `interval` (milliseconds, e.g. 3600000 for 1h). For taxonomy, GET /prediction-markets/taxonomy lists the PMCS codes used to filter searches.", "contact": { "name": "Lukka Prediction Markets", "url": "https://predictionmarketdata.io", "email": "data@lukka.global" } }, "servers": [ { "url": "https://api.predictionmarketdata.io", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "X402Payment": [] } ], "components": { "securitySchemes": { "X402Payment": { "type": "apiKey", "in": "header", "name": "x-payment", "description": "Base64-encoded x402 payment payload (USDC on Base mainnet, eip155:8453). See https://www.x402.org." } }, "responses": { "PaymentRequired": { "description": "x402 payment required. Sign and retry with `x-payment` header.", "headers": { "payment-required": { "description": "Base64-encoded payment requirements.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "error": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "example": "eip155:8453" }, "amount": { "type": "string", "example": "1000" }, "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" } } } } } } } } } }, "parameters": { "FromTs": { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "UTC start timestamp (ISO-8601)." }, "ToTs": { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "UTC end timestamp (ISO-8601)." }, "IntervalMs": { "name": "interval", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Bucket size in milliseconds (e.g. 300000 = 5m, 3600000 = 1h)." } } }, "paths": { "/prediction-markets/taxonomy": { "get": { "operationId": "getTaxonomy", "summary": "List PMCS taxonomy codes", "description": "Valid PMCS taxonomy codes used to filter prediction-market searches.", "tags": ["Taxonomy"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "responses": { "200": { "description": "Taxonomy entries.", "content": { "application/json": { "example": { "taxonomy": [ { "code": "GEO", "level": "categories", "name": "Geopolitical", "taxonomy_id": "categories:GEO", "taxonomy_version": "3.5", "updated_at": "2026-02-12T00:00:00Z" } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/prediction-markets": { "get": { "operationId": "searchPredictionMarkets", "summary": "Search prediction markets", "description": "Search, filter, and sort prediction markets across exchanges (Kalshi, Polymarket, Gemini).", "tags": ["Markets"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Free-text query across market and event names." }, { "name": "event_ticker", "in": "query", "schema": { "type": "string" }, "description": "Exact event identifier." }, { "name": "entity_code", "in": "query", "schema": { "type": "string", "enum": ["KALSHI", "POLYMARK", "GMNI"] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["Open", "Closed", "Unknown"] } }, { "name": "outcome_type", "in": "query", "schema": { "type": "string", "enum": ["Binary", "Multi"] } }, { "name": "pmcs_category", "in": "query", "schema": { "type": "string" } }, { "name": "pmcs_supersector", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string" }, "description": "e.g. total_volume_24hr, total_open_interest_usd, end_ts." }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "volume_min", "in": "query", "schema": { "type": "number" } }, { "name": "volume_max", "in": "query", "schema": { "type": "number" } }, { "name": "volume_1hr_min", "in": "query", "schema": { "type": "number" } }, { "name": "volume_1hr_max", "in": "query", "schema": { "type": "number" } }, { "name": "open_interest_min", "in": "query", "schema": { "type": "number" } }, { "name": "open_interest_max", "in": "query", "schema": { "type": "number" } }, { "name": "trade_count_min", "in": "query", "schema": { "type": "integer" } }, { "name": "trade_count_max", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated list of prediction-market events.", "content": { "application/json": { "example": { "pagination": { "hasMore": true, "limit": 2, "nextOffset": 2, "offset": 0, "total": 30834 }, "predictionMarkets": [ { "event_ticker": "KXNBAGAME-26JUN08SASNYK.KALSHI", "event_name": "Game 3: San Antonio at New York", "entity_code": "KALSHI", "entity_event_category": "Sports", "event_outcome_type": "Multi", "end_ts": "2026-06-23T00:30:00Z", "is_series": true, "pmcs_categories": ["SPT", "BSKTBL", "NBA"], "event_outcomes": [ { "market_id": "KXNBAGAME-26JUN08SASNYK-NYK_yes.KALSHI", "outcome_name": "New York", "percentage": 0.54, "status": "Open", "volume": 7872349.97 } ] } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/prediction-markets/similar": { "get": { "operationId": "findSimilarMarkets", "summary": "Find similar prediction markets", "description": "Semantically similar prediction markets given an event_ticker.", "tags": ["Markets"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "name": "event_ticker", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Similar events with similarity scores.", "content": { "application/json": { "example": { "similar": [{ "event_ticker": "spurs-vs-knicks-game-3.POLYMARK", "score": 0.91 }] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/market-overview": { "get": { "operationId": "getMarketOverview", "summary": "Volume by exchange (time-bucketed)", "description": "Time-bucketed prediction market volume and trade-count by exchange.", "tags": ["Analytics"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "": "#/components/parameters/FromTs" }, { "": "#/components/parameters/ToTs" }, { "": "#/components/parameters/IntervalMs" } ], "responses": { "200": { "description": "Volume buckets per exchange.", "content": { "application/json": { "example": { "dataType": "prediction-volume-by-exchange", "count": 144, "data": [ { "time": "2026-06-07T00:00:00Z", "sourceId": 4008, "entityCode": "GMNI", "entityName": "Gemini", "instrumentType": "PREDICTION_MARKET", "volumeUsd": "1700.9", "tradeCount": 37, "volume": "4299.0" } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/market-news": { "get": { "operationId": "getMarketNews", "summary": "Prediction-market news", "description": "Recent news relevant to prediction markets within a publish-date window.", "tags": ["News"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "name": "publishDateFrom", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "publishDateTo", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "News articles.", "content": { "application/json": { "example": { "news": [ { "newsID": "c42c42e75aa142f3943236f8e7579e6f", "publishDateTime": "2026-06-07T23:50:10Z", "title": "Polymarket Under Fire: 20% of Dispute Judges Had Stake in Outcomes They Ruled On", "snippet": "Polymarket faces scrutiny as 20% of dispute judges had financial stakes in outcomes.", "url": "https://bitcoinworld.co.in/polymarket-conflict-of-interest-judges-betting/", "entityName": "BitcoinWorld", "entityCode": "BTCWRLD", "newsCategory": "prediction-markets", "contentType": "breaking-news", "sentiment": "Negative" } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/market-statistics/sectors": { "get": { "operationId": "getSectorStatistics", "summary": "Aggregated sector statistics", "description": "Aggregated prediction-market statistics by sector.", "tags": ["Analytics"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "responses": { "200": { "description": "Sector statistics.", "content": { "application/json": {} } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/market-recap": { "get": { "operationId": "getMarketRecap", "summary": "Narrative market recap", "description": "LLM-generated narrative recap of recent prediction-market activity.", "tags": ["Analytics"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "responses": { "200": { "description": "Recap paragraphs and meta.", "content": { "application/json": { "example": { "paragraphs": ["The prediction market saw a total 24-hour volume of $264.4M across 16,512 active markets."], "generatedAt": "2026-06-08T20:21:32.616Z", "source": "llm", "volumeChange": null, "predictionVolume24h": 264416064.6, "newsCount": 0 } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/open-interest": { "get": { "operationId": "getOpenInterest", "summary": "Open interest by exchange", "description": "Time-series of prediction-market open interest by exchange (USD).", "tags": ["Analytics"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "": "#/components/parameters/FromTs" }, { "": "#/components/parameters/ToTs" }, { "": "#/components/parameters/IntervalMs" } ], "responses": { "200": { "description": "Open-interest buckets per exchange.", "content": { "application/json": { "example": { "dataType": "prediction-open-interest-summary", "count": 48, "data": [ { "time": "2026-06-07T00:00:00Z", "sourceId": 4137, "entityCode": "POLYMARK", "entityName": "Polymarket", "openInterestUsd": "297477595.47" } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/price-history": { "get": { "operationId": "getPriceHistory", "summary": "Historical price candles for a market", "description": "Historical pricing for a single prediction market on one exchange.", "tags": ["Analytics"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "name": "event", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Event ticker or market identifier." }, { "name": "exchangeId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Numeric exchange ID. 4141=Kalshi, 4137=Polymarket, 4008=Gemini." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "interval", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Candles.", "content": { "application/json": { "example": { "dataType": "predictionHistoryCandles", "sourceId": 4141, "eventTicker": "KXNBAGAME-26JUN08SASNYK.KALSHI", "count": 1, "firstDate": "2026-06-07T20:25:00Z", "lastDate": "2026-06-07T20:25:00Z", "data": [ { "ts": "2026-06-07T20:25:00Z", "markets": [ { "lukkaSymbol": "KXNBAGAME-26JUN08SASNYK-NYK_yes.KALSHI", "openPrice": "0.55", "closePrice": "0.55", "highPrice": "0.55", "lowPrice": "0.55", "volume": "5817.81", "volumeUsd": "3199.79", "tradeCount": 49 } ] } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/exchanges": { "get": { "operationId": "listExchanges", "summary": "List exchanges (VASPs)", "description": "Prediction-market exchanges and entity metadata (Lukka VASP).", "tags": ["Reference"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "primary_location", "in": "query", "schema": { "type": "string" } }, { "name": "vasp_classification", "in": "query", "schema": { "type": "string" } }, { "name": "vasp_score", "in": "query", "schema": { "type": "string" } }, { "name": "vasp_score_gt", "in": "query", "schema": { "type": "string" } }, { "name": "vasp_score_lt", "in": "query", "schema": { "type": "string" } }, { "name": "vast_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exchange records.", "content": { "application/json": { "example": { "exchanges": [ { "entityCode": "KALSHI", "lukkaVasp": "Kalshi", "lukkaVaspId": "LV40C47CFE3", "primaryLocation": "United States", "startTs": "2022-05-01T00:00:00Z", "status": "Active", "vaspClassification": "Centralized", "vaspScore": "59.9225", "vaspType": "Prediction", "website": "https://kalshi.com/", "letterGrade": "B2" } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/prediction-markets/pmcs-stats": { "get": { "operationId": "getPmcsStats", "summary": "PMCS counts by hierarchy/exchange", "description": "Live PMCS counts by hierarchy and exchange.", "tags": ["Taxonomy"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "responses": { "200": { "description": "PMCS statistics.", "content": { "application/json": { "example": { "last_updated": "2026-06-08T20:13:30.068517+00:00", "pmcs_stats": { "category_codes": [ { "code": "SPT", "count": 16821, "entityCodes": [{ "code": "KALSHI", "count": 11909 }, { "code": "POLYMARK", "count": 3714 }] } ] } } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } }, "/prediction-total-volume": { "get": { "operationId": "getTotalVolume", "summary": "Total volume across all exchanges", "description": "Time-bucketed total prediction-market volume across all exchanges.", "tags": ["Analytics"], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001000" }, "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }] }, "parameters": [ { "": "#/components/parameters/FromTs" }, { "": "#/components/parameters/ToTs" }, { "": "#/components/parameters/IntervalMs" } ], "responses": { "200": { "description": "Volume buckets per exchange.", "content": { "application/json": { "example": { "dataType": "prediction-total-volume-summary", "count": 48, "data": [ { "time": "2026-06-07T00:00:00Z", "sourceId": 4137, "entityCode": "POLYMARK", "entityName": "Polymarket", "totalVolumeUsd": "6034873863.04" } ] } } } }, "402": { "": "#/components/responses/PaymentRequired" } } } } } }