# PredictionMarketDataAPI

> Prediction market prices, implied probabilities, 24 hour volumes, movers, resolutions and price history for AI agents. Derived from public Polygon chain data (Polymarket CTF Exchange contracts). Not affiliated with, endorsed by or sourced from any venue's API. One key, or pay per request in USDC over x402.

## Authentication
Send `X-API-Key: pmd_live_...`. Free key: `POST https://predictionmarketdataapi.com/api/v1/auth/keys` with `{"email": "..."}`. No key? GET any data endpoint and you receive a 402 with the USDC price (x402).
Free at volume: the same endpoints are on RealtimeAPI.ai as feed `predictiondata` (https://api.realtimeapi.ai/v1/predictiondata/...). A free RealtimeAPI key (`POST https://api.realtimeapi.ai/keys/free`) gives 1,000 calls a month across every feed. Setup prompt for any agent: https://predictionmarketdataapi.com/start/prompt.txt

## First calls
1. `GET /api/v1/markets?q=fed&limit=5` (MCP: `predictions_search`): markets matching a topic, with probabilities.
2. `GET /api/v1/markets/top` (MCP: `predictions_market`): every outcome of the busiest live market.
3. `GET /api/v1/movers?window=24h` (MCP: `predictions_movers`): largest probability changes.

## Endpoints and prices (USDC per request without a key)
- `GET /api/v1/markets`: Search and list prediction markets with the latest implied probability, 24 hour volume and status. Filter by category, status or text; sort by volume, new or recent. $0.005. Refreshes every 5 minutes. Tier: free.
- `GET /api/v1/markets/{market_id}`: One market: every outcome's last traded price and implied probability, 24 hour volume and trade count, status and resolution. The id is a condition id, an outcome token id, or `top` for the busiest live market. $0.010. Refreshes every 15 seconds. Tier: free.
- `GET /api/v1/markets/{market_id}/history`: Price history of one market as OHLC bars per outcome (1m, 1h or 1d) with volume, for charts and backtests. Historical rows never change; resolution is reported separately so a backtest cannot see the outcome early. $0.020. Refreshes every 60 seconds. Tier: pro.
- `GET /api/v1/movers`: Markets whose implied probability moved most over 1 hour, 24 hours or 7 days, with a volume floor so thin markets do not dominate. $0.010. Refreshes every 5 minutes. Tier: free.
- `GET /api/v1/resolved`: Recently resolved markets with the winning outcome, resolution time and the last price before resolution. $0.010. Refreshes every 5 minutes. Tier: free.
- `GET /api/v1/markets/{market_id}/consensus`: Cross-venue view of one question: the real-money probability (volume weighted, fee adjusted) and the matched play-money venues shown beside it, with dispersion. $0.015. Refreshes every 60 seconds. Tier: free.
- `GET /api/v1/calibration`: How often markets priced at each probability bucket resolved yes, by category and period: the reliability of market prices as forecasts. $0.015. Refreshes every 24 hours. Tier: pro.

## Tiers
- Free: 10/min, 5/day.
- Pro: 60/min, 20000/day. Adds history and calibration. Passes: 1h $1.00, 1d $3.00, 7d $8.00. No subscriptions.

## Units
Prices are integer micro-USD (`price_micro`, 1000000 = $1.00, so a price is also the implied probability times 1,000,000). Probabilities are integer basis points (`prob_bps`, 10000 = 100%). Volumes are integer micro-USD. Times are UTC ISO 8601.