API Documentation

PredictMarkets exposes a REST API (and WebSocket) for accessing Premier League prediction market data.

Base URL: https://api.plpredictionmarkets.com · Full OpenAPI spec available at /docs (Swagger UI) when running the backend.

Arbitrage response guide

Spread

Raw probability disagreement between Polymarket and Kalshi. A large spread is a signal, but it is not automatically tradable.

True arbitrage

Fee-adjusted profit after pairing the cheaper YES side with the opposite NO side on the other platform.

Trade legs

leg1 and leg2 show the exact platform, side, and price cents used by the calculator. Always re-check live prices before trading.

GET/api/v1/matches

Fetch all current Premier League matches with grouped markets from both Polymarket and Kalshi. Returns match winner, spreads, over/under, and BTTS markets.

Example response

[
  {
    "match_id": "arsenal-vs-chelsea-2026-03-08",
    "home_team": "Arsenal",
    "away_team": "Chelsea",
    "match_date": "2026-03-08T15:00:00Z",
    "markets": [ ... ]
  }
]

GET/api/v1/matches/:id

Get a single match by ID with all associated markets and cross-platform spreads.

Params: id (path) — Match identifier (e.g. arsenal-vs-chelsea-2026-03-08)

Example response

{
  "match_id": "arsenal-vs-chelsea-2026-03-08",
  "home_team": "Arsenal",
  "away_team": "Chelsea",
  "markets": [ ... ],
  "arbitrage": { ... }
}

GET/api/v1/futures

Season-long markets — title winner, top 4, relegation odds from Kalshi.

Example response

{
  "title_winner": [ ... ],
  "relegation": [ ... ]
}

GET/api/v1/analytics

Aggregate analytics across all markets — total volume, liquidity, platform distribution, top arbitrage opportunities.

Example response

{
  "total_markets": 142,
  "total_volume": 2450000,
  "platform_split": { ... }
}

GET/api/v1/markets/arbitrage

Find cross-platform Polymarket/Kalshi price gaps with fee-adjusted profitability, executable trade legs, ROI, and source-platform links.

Params: min_spread (query, default 3), only_true_arb (query, default false)

Example response

{
  "opportunities": [
    {
      "match_label": "Arsenal vs Chelsea",
      "outcome": "Arsenal",
      "spread": 8.2,
      "combined_cost": 0.91,
      "net_profit_per_share": 0.061,
      "is_true_arbitrage": true,
      "roi_pct": 6.7,
      "leg1": { "platform": "polymarket", "side": "YES", "price_cents": 42 },
      "leg2": { "platform": "kalshi", "side": "NO", "price_cents": 49 }
    }
  ],
  "true_arbitrage_count": 1,
  "avg_roi": 6.7,
  "best_roi": 6.7
}

GET/api/v1/price-history/:match_id

Historical price snapshots for a match. Used for price charts and trend analysis.

Params: match_id (path), hours (query, default 24) — How far back to look

Example response

[
  {
    "timestamp": "2026-03-07T12:00:00Z",
    "outcome": "Arsenal",
    "price": 0.62,
    "platform": "polymarket"
  }
]

WS/ws/prices

WebSocket endpoint for real-time Polymarket price streaming. Relays live price updates for all tracked PL markets.

Params: N/A — connect and receive JSON messages

Example response

{
  "match_id": "arsenal-vs-chelsea-2026-03-08",
  "outcome": "Arsenal",
  "price": 0.63,
  "timestamp": "2026-03-08T14:32:01Z"
}

Self-hosted

See the GitHub repo for setup instructions. The backend runs on FastAPI with Docker Compose support for easy local development.