Sports Prediction API Documentation

Quickstart

Start with a games or edges request. Response values below are illustrative; game availability, model versions and source freshness change. For background, read our research summary. research summary.

curl -H "X-API-Key: sk_live_YOUR_KEY" https://zenhodl.net/v1/edges

// NCAAMB, Purdue (away), fair_wp=0.74, market_ask=0.63, gap=+11c
// Our fair value is 74c; this venue asks 63c. Compare venues and take the best price.

pip install zenhodl

from zenhodl import ZenHodl

client = ZenHodl()                  # keyless: sample + health
sample = client.edges_sample()      # keyless preview: 15-min delay, NBA+NHL only — NOT your Free tier

client = ZenHodl("sk_live_YOUR_KEY")

for s in client.edges(min_edge=8)["signals"]:
    print(f"{s['sport']} {s['team']}: "
          f"fair={s['fair_wp']:.0%} ask={s['market_ask']:.0%} "
          f"edge=+{s['edge']*100:.1f}c ({s['confidence']})")

games = client.games(sport="MLB")   # delayed on Free; real-time on Starter+

csv_bytes = client.predictions()

Which Endpoint Should I Use?

Free keys can call /v1/games and /v1/edges with a 5-minute delay and a 500 request monthly cap. Real-time predictions, fair lines, WebSocket, and webhooks require an eligible paid tier.

Key Concepts

Authentication

All authenticated endpoints require an API key. Pass it via the X-API-Key header:

# curl
curl -H "X-API-Key: sk_live_your_key_here" https://zenhodl.net/v1/games

# Python
import requests
headers = {"X-API-Key": "sk_live_your_key_here"}
games = requests.get("https://zenhodl.net/v1/games", headers=headers).json()

// JavaScript (fetch)
const resp = await fetch("https://zenhodl.net/v1/games", {
  headers: { "X-API-Key": "sk_live_your_key_here" }
});
const data = await resp.json();

Create a free account to receive a key for delayed games and edges, or choose a paid plan for real-time access. Keys start with sk_live_. Keep it secret — treat it like a password.

Rate Limits

Rate limits are per-minute. Every authenticated API response includes these headers (Remaining already counts the current request). Public endpoints return 429 with Retry-After.

Monthly usage is metered on authenticated REST endpoints. /v1/usage is excluded so you can always inspect your own usage without consuming quota. WebSocket connection limits are enforced separately from monthly REST usage.

Errors

All errors return JSON with a detail field:

{"detail": "Rate limit exceeded (300 req/min for pro tier)."}

Transparency endpoints (free, no auth)

Anyone can audit our results by downloading the strategy-redacted trade ledger and the analysis code. These endpoints are unauthenticated and serve the proof data behind our public results pages — including the 2026-07-21 retraction of our earlier CLV-gap claim. We publish retractions with the same prominence we gave the claims.

curl -O https://zenhodl.net/api/trades.jsonl

curl -O https://zenhodl.net/api/exchange_fill_reconciliation.jsonl

curl -O https://zenhodl.net/api/trades.jsonl
curl -O https://zenhodl.net/api/exchange_fill_reconciliation.jsonl
curl -O https://zenhodl.net/api/verify_clv_gap.py
python3 verify_clv_gap.py trades.jsonl

GET /v1/health

System health check. No authentication required. Use this to verify the API is running and check how many games are active.

curl https://zenhodl.net/v1/health

Response:

{
  "status": "ok",
  "uptime_seconds": 3600.5,
  "active_games": 12,
  "sports_loaded": ["NBA", "WNBA", "NCAAMB", "NCAAWB", "CFB", "NFL", "NHL", "MLB"],
  "last_espn_poll": "2026-03-22T19:30:00Z",
  "last_ws_update": "2026-03-22T19:30:01Z"
}

GET /v1/games

All live games with ML fair win probabilities and market prices. This is the primary endpoint for getting a full view of every tracked game.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/games?sport=NBA&venue=polymarket"

import requests

games = requests.get(
    "https://zenhodl.net/v1/games",
    headers={"X-API-Key": "sk_live_..."},
    params={"sport": "NBA"}
).json()

for g in games["games"]:
    edge = (g["home_fair_wp"] - (g["home_market_ask"] or 0)) * 100
    print(f"{g['event_title']} | {g['time_display']} | edge: {edge:+.1f}c")

Response:

{
  "timestamp": "2026-03-22T19:30:00Z",
  "count": 5,
  "games": [{
    "sport": "NBA",
    "game_id": "401810889",
    "event_title": "Knicks vs. Wizards",
    "home_team": "NY", "away_team": "WSH",
    "home_score": 78, "away_score": 65,
    "period": 3, "seconds_remaining": 420.0,
    "time_display": "Q3 7:00",
    "status": "live",
    "home_fair_wp": 0.82,
    "away_fair_wp": 0.18,
    "home_market_ask": 0.75,
    "away_market_ask": 0.27,
    "home_edge": 0.07,
    "away_edge": -0.09,
    "model_confidence": "medium",
    "is_score_change": false,
    "last_updated": "2026-03-22T19:29:55Z",
    "venue_prices": {
      "polymarket": {
        "venue": "polymarket",
        "home_ask_c": 75.0, "away_ask_c": 27.0,
        "home_bid_c": 74.0, "away_bid_c": 26.0,
        "quote_ts": "2026-03-22T19:29:53Z",
        "quote_age_seconds": 2.1
      },
      "kalshi": {
        "venue": "kalshi",
        "home_ask_c": 76.0, "away_ask_c": 26.0,
        "home_bid_c": 74.0, "away_bid_c": 25.0,
        "quote_ts": "2026-03-22T18:59:10Z",
        "quote_age_seconds": 1843.0
      }
    },
    "best_home_venue": "polymarket",
    "best_away_venue": "kalshi",
    "batting_half": null
  }]
}

Response fields

GET /v1/edges

Where our fair value differs from a venue's price — only games where our fair win probability and the venue ask diverge by at least min_edge. Use it for line-shopping and best-price comparison, not as a profit promise. The edge field is just fair_wp − market_ask (before fees and slippage); see the CLV retraction and amendment for the limits of terminal in-play closing-line measurements.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/edges?sport=NCAAMB&min_edge=10"

edges = requests.get(
    "https://zenhodl.net/v1/edges",
    headers={"X-API-Key": "sk_live_..."},
    params={"sport": "NCAAMB", "min_edge": 10}
).json()

for s in edges["signals"]:
    print(f"BUY {s['team']} @ {s['market_ask']:.0%} "
          f"(fair: {s['fair_wp']:.0%}, edge: +{s['edge']*100:.1f}c)")

Response:

{
  "timestamp": "2026-03-22T19:30:00Z",
  "count": 1,
  "min_edge": 0.10,
  "min_edge_c": 10.0,
  "signals": [{
    "sport": "NCAAMB",
    "game_id": "401810889",
    "event_title": "Purdue vs. Illinois",
    "team": "Purdue",
    "side": "away",
    "fair_wp": 0.74,
    "market_ask": 0.63,
    "edge": 0.11,
    "edge_c": 11.0,
    "period": 2,
    "seconds_remaining": 480.0,
    "score": "52-44",
    "confidence": "low",
    "is_score_change": false,
    "timestamp": "2026-03-22T19:29:55Z",
    "model_fair_c": 74.0,
    "bot_fair_c": 68.5,
    "bot_edge_c": 5.5,
    "bot_lane": "shadow",
    "edge_basis": "model_pre_blend"
  }]
}

Illustrative values. Here an 11c model edge becomes 5.5c after the bot's 50/50 market blend, so confidence is low; NCAAMB is a shadow sport for our bot.

Response fields

GET /v1/sports

Available sports and model metadata. Useful for discovering what models are loaded and their backtest performance.

Public API contract: NBA, WNBA, NCAAMB, NCAAWB, CFB, NFL, NHL and MLB. Internal soccer, tennis, CS2 and League of Legends runners are separate and are not promised by this endpoint.

curl -H "X-API-Key: sk_live_..." https://zenhodl.net/v1/sports

Response:

{
  "sports": [{
    "sport": "NCAAMB",
    "model_type": "xgb_isotonic",
    "train_games": 15230,
    "elo_teams": 362,
    "features": ["score_diff", "seconds_remaining", "period",
                 "time_fraction", "elo_diff", "pregame_wp"],
    "backtest_wr": 0.738,
    "backtest_c_per_trade": 12.0
  }]
}

GET /v1/predictions/latest

Download today's pre-game fair probability predictions as CSV. Also available by date: /v1/predictions/{YYYYMMDD}

# Today's predictions
curl -H "X-API-Key: sk_live_..." https://zenhodl.net/v1/predictions/latest -o predictions.csv

# Specific date
curl -H "X-API-Key: sk_live_..." https://zenhodl.net/v1/predictions/20260322 -o predictions.csv

Sample CSV row:

CSV files include a license header with your email and download token. See data license.

POST /v1/backtest

Run a WP model backtest with custom strategy parameters against our 25M+ row dataset. Test different edge thresholds, periods, and fee assumptions.

curl -X POST -H "X-API-Key: sk_live_..." -H "Content-Type: application/json" \
  -d '{"sport":"NCAAMB","min_edge_c":10,"min_period":2,"seasons":["2025-26"]}' \
  https://zenhodl.net/v1/backtest

result = requests.post(
    "https://zenhodl.net/v1/backtest",
    headers={"X-API-Key": "sk_live_..."},
    json={"sport": "NCAAMB", "min_edge_c": 10, "min_period": 2}
).json()

s = result["summary"]
print(f"{s['total_trades']} trades, {s['win_rate']:.1%} WR, "
      f"+{s['c_per_trade_net']:.1f}c/trade net")

Response:

{
  "summary": {
    "total_trades": 854,
    "wins": 630,
    "losses": 224,
    "win_rate": 0.738,
    "gross_pnl_c": 12024.0,
    "net_pnl_c": 10280.0,
    "avg_edge_c": 11.8,
    "c_per_trade_net": 12.0,
    "max_drawdown_c": 340.0,
    "best_streak": 18,
    "worst_streak": 5
  },
  "by_edge": [
    {"bucket": "8-10c", "trades": 412, "win_rate": 0.71, "c_per_trade": 9.8},
    {"bucket": "10-12c", "trades": 198, "win_rate": 0.76, "c_per_trade": 14.2},
    {"bucket": "12-15c", "trades": 144, "win_rate": 0.79, "c_per_trade": 16.5}
  ],
  "by_period": [
    {"period": 1, "trades": 320, "win_rate": 0.72, "c_per_trade": 10.1},
    {"period": 2, "trades": 534, "win_rate": 0.75, "c_per_trade": 13.2}
  ],
  "sample_trades": [{"game_id": "...", "side": "away", "edge_c": 11.1, "entry_c": 63.0, "profit_c": 37.0, "won": true}]
}

GET /v1/backtest/sports

List available sports and seasons for backtesting.

curl -H "X-API-Key: sk_live_..." https://zenhodl.net/v1/backtest/sports

Response:

{
  "sports": {
    "NCAAMB": {"seasons": ["2023-24", "2024-25", "2025-26"], "files": 3, "model_available": true},
    "NBA": {"seasons": ["2023-24", "2024-25", "2025-26"], "files": 3, "model_available": true},
    "CFB": {"seasons": ["2023", "2024"], "files": 2, "model_available": true}
  }
}

WS /v1/ws/stream

WebSocket pushes are scheduled every 5 seconds. That is a transport interval, not a guarantee that a new game state or fresh quote exists for every source. Inspect the source timestamps and quote-age fields.

const API_KEY = "sk_live_your_key_here";
const ws = new WebSocket(
  "wss://zenhodl.net/v1/ws/stream",
  ["zenhodl.v1", API_KEY]
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === "edge_alert") {
    const d = msg.data;
    console.log(`EDGE: ${d.sport} ${d.team} | `
      + `fair=${d.fair_wp}c ask=${d.market_ask}c edge=+${d.edge}c`);
  }

  if (msg.type === "game_update") {
    const d = msg.data;
    console.log(`${d.event_title} ${d.time_display} | `
      + `fair=${d.home_fair_wp} ask=${d.home_market_ask}`);
  }
};

ws.onclose = () => setTimeout(() => location.reload(), 5000); // auto-reconnect

import asyncio, websockets, json

API_KEY = "sk_live_your_key_here"

async def stream():
    uri = "wss://zenhodl.net/v1/ws/stream"
    async with websockets.connect(uri, subprotocols=["zenhodl.v1", API_KEY]) as ws:
        async for raw in ws:
            msg = json.loads(raw)
            if msg["type"] == "edge_alert":
                d = msg["data"]
                print(f"EDGE: {d['sport']} {d['team']} "
                      f"fair={d['fair_wp']}c ask={d['market_ask']}c "
                      f"edge=+{d['edge']}c ({d['confidence']})")

asyncio.run(stream())

Message types

{"type": "game_update", "data": {
  "sport": "NBA", "game_id": "401810889", "event_title": "Knicks vs. Wizards",
  "home_team": "NY", "away_team": "WSH", "home_score": 78, "away_score": 65,
  "period": 3, "time_display": "Q3 7:00",
  "home_fair_wp": 0.82, "away_fair_wp": 0.18,
  "home_market_ask": 0.75, "away_market_ask": 0.27,
  "home_edge": 0.07, "away_edge": -0.09
}}

{"type": "edge_alert", "data": {
  "sport": "NCAAMB", "team": "Purdue", "side": "away",
  "fair_wp": 74.1, "market_ask": 63.0, "edge": 11.1,
  "score": "52-44", "confidence": "low"
}}

GET /v1/predict/{sport}/live

All live games with win probabilities and multi-venue edges. Returns fair ML odds and per-venue pricing from Polymarket, Kalshi, and major sportsbooks. Starter+ tier (Free keys get a 403; use the delayed /v1/games and /v1/edges).

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/predict/NBA/live"

import requests

resp = requests.get(
    "https://zenhodl.net/v1/predict/NBA/live",
    headers={"X-API-Key": "sk_live_..."}
).json()

for g in resp["games"]:
    print(f"{g['home_team']} vs {g['away_team']}: "
          f"P(home)={g['home_win_prob']:.0%} ML={g['fair_home_ml']}")
    for venue, v in (g.get("venues") or {}).items():
        if v.get("home_edge") and v["home_edge"] > 0.05:
            print(f"  model minus {venue} price: {v['home_edge']:.1%}")

const resp = await fetch("https://zenhodl.net/v1/predict/NBA/live", {
  headers: { "X-API-Key": "sk_live_..." }
});
const { games } = await resp.json();
games.forEach(g => console.log(`${g.home_team} ${g.fair_home_ml} | ${g.away_team} ${g.fair_away_ml}`));

Response:

{
  "timestamp": "2026-03-28T22:00:00Z",
  "sport": "NBA",
  "count": 5,
  "games": [{
    "game_id": "401585432",
    "sport": "NBA",
    "home_team": "LAL", "away_team": "BOS",
    "home_score": 78, "away_score": 75,
    "period": 3, "clock": "Q3 8:42",
    "home_win_prob": 0.72,
    "away_win_prob": 0.28,
    "model_confidence": "high",
    "fair_home_ml": -257,
    "fair_away_ml": 215,
    "venues": {
      "Polymarket": {"home_ask": 0.62, "home_edge": 0.10, "quote_ts": "2026-03-28T21:59:58Z", "quote_age_seconds": 2.4},
      "Kalshi": {"home_ask": 0.63, "home_edge": 0.09, "quote_ts": "2026-03-28T21:30:12Z", "quote_age_seconds": 1787.6},
      "DraftKings": {"home_ml": "-150", "home_implied": 0.60, "home_edge": 0.12, "quote_ts": "2026-03-28T21:59:40Z", "quote_age_seconds": 20.1},
      "FanDuel": {"home_ml": "-165", "home_implied": 0.623, "home_edge": 0.097, "quote_ts": "2026-03-28T21:59:41Z", "quote_age_seconds": 19.0}
    },
    "best_home_venue": "DraftKings",
    "batting_half": null
  }]
}

batting_half (added 2026-09-25): MLB only, "top" (away team batting) or "bottom" (home team batting); null for every other sport and for pregame predictions. period and clock do not encode this on their own.

Per-venue freshness

GET /v1/predict/{sport}/pregame

Today's upcoming games with Elo-based pregame win probabilities. No live game state needed — uses Elo ratings only. Starter+ tier.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/predict/NBA/pregame"

Response:

{
  "sport": "NBA", "count": 8,
  "games": [{
    "game_id": "401810900",
    "home_team": "LAL", "away_team": "BOS",
    "home_win_prob": 0.42, "away_win_prob": 0.58,
    "fair_home_ml": 138, "fair_away_ml": -138,
    "status": "scheduled"
  }]
}

GET /v1/predict/{sport}/{game_id}

Single game detail with full model output, multi-venue edges, and game state. Starter+ tier.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/predict/NBA/401585432"

GET /v1/fair-lines/{sport}

Fair moneyline odds in American format for all live games. Designed for integration into odds comparison tools. Starter+ tier.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/fair-lines/NBA"

Response:

{
  "sport": "NBA", "count": 5,
  "lines": [{
    "game_id": "401585432",
    "home_team": "LAL", "away_team": "BOS",
    "home_win_prob": 0.72, "away_win_prob": 0.28,
    "fair_home_ml": -257, "fair_away_ml": 215,
    "clock": "Q3 8:42", "status": "live"
  }]
}

GET /v1/usage

Your current month's API usage. Track request counts against your monthly cap.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/usage"

Response:

{
  "month": "2026-03",
  "requests_used": 4521,
  "requests_cap": 30000,
  "by_endpoint": {
    "/v1/predict/NBA/live": 3200,
    "/v1/predict/NHL/live": 821,
    "/v1/fair-lines/NBA": 500
  },
  "tier": "starter",
  "resets_at": "2026-04-01T00:00:00+00:00"
}

Model Quality & Analytics

Endpoints for evaluating model quality, tracking closing line value (CLV), and monitoring data venues.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/model/performance?sport=NBA"

{
  "sports": [{
    "sport": "NBA",
    "brier_score": 0.139,
    "roc_auc": 0.890,
    "ece": 0.106,
    "accuracy": 0.803,
    "model_type": "Split-Phase",
    "trained_date": "2026-03-24T15:52:54Z",
    "n_test_games": 90,
    "conformal_table": [{"tf_lo": 0.0, "tf_hi": 0.1, "width": 0.029, "n_samples": 35672}, ...]
  }]
}

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/model/clv?sport=NBA&days=30"

{
  "total_signals": 142,
  "avg_clv_c": 3.8,
  "clv_beat_pct": 61.2,
  "by_sport": [{"sport": "NBA", "count": 42, "avg_clv_c": 4.1, "clv_beat_pct": 64.3}],
  "by_edge_bucket": [{"bucket": "8-12c", "count": 85, "avg_clv_c": 2.1, "clv_beat_pct": 55.3}]
}

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/venues"

{
  "venues": [
    {"venue": "polymarket", "status": "connected", "connection_type": "websocket", "markets_active": 7770},
    {"venue": "kalshi", "status": "connected", "connection_type": "websocket"},
    {"venue": "draftkings", "status": "polling", "connection_type": "rest_polling"}
  ]
}

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/snapshots/NBA/20260330"

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/predictions/batch?start=20260301&end=20260330&sport=NBA" -o batch.csv

Webhooks

Register a URL for signed POST notifications when a model-versus-venue price gap matches your threshold. Client polling is unnecessary for delivery; that does not guarantee fresh upstream quotes, every venue update, or an executable fill. Starter+ tier.

curl -X POST -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/hook", "filters": {"sport": "NBA", "min_edge_c": 10}}' \
  "https://zenhodl.net/v1/webhooks"

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/webhooks"

curl -X DELETE -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/webhooks/abc123"

Watchlists & Preferences

Store user-specific game lists and notification settings. These endpoints are useful when you want durable scanner filters or alert automation tied to an account.

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/watchlists"

curl -X POST -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "High Edge NBA", "sports": ["NBA"], "teams": [], "min_edge_c": 10, "max_entry_c": 78}' \
  "https://zenhodl.net/v1/watchlists"

curl -H "X-API-Key: sk_live_..." "https://zenhodl.net/v1/preferences"

curl -X PUT -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"daily_summary": true, "weekly_summary": true, "alert_threshold_c": 9, "favorite_sports": ["NBA", "NHL"], "timezone": "America/New_York"}' \
  "https://zenhodl.net/v1/preferences"

Confidence Intervals

Where a model has a conformal table, prediction responses can include confidence_interval. These are model-specific estimated bands; their coverage depends on the evaluation sample and current data regime. They do not establish a guaranteed win probability or a safe position size.

{
  "home_fair_wp": 0.72,
  "confidence_interval": {
    "lower": 0.68,
    "upper": 0.76,
    "width": 0.08
  }
}

Band widths come from the available model table and game-state bucket. The values above are illustrative; do not assume all sports or later game states have the same width or more certainty.

Free Samples

Two public sample endpoints — no API key needed. Signed-in free accounts get broader delayed access on the authenticated API.

curl https://zenhodl.net/v1/predictions/sample.csv -o sample.csv

curl https://zenhodl.net/v1/edges/sample

{
  "count": 2,
  "delay_minutes": 15,
  "sports": ["NBA", "NHL"],
  "note": "Delayed 15 min (NBA+NHL only). Upgrade for real-time across 8 sports.",
  "units": {
    "fair_wp": "cents (0-100 scale) ...",
    "edge": "cents (0-100 scale) ...",
    "fair_wp_decimal": "decimal probability, 0.0-1.0 ...",
    "edge_decimal": "decimal probability, 0.0-1.0 ..."
  },
  "signals": [
    {"sport": "NBA", "team": "NY", "edge": 11.2, "fair_wp": 78.5, "edge_decimal": 0.112, "fair_wp_decimal": 0.785, "confidence": "high"},
    {"sport": "NHL", "team": "BOS", "edge": 9.1, "fair_wp": 71.3, "edge_decimal": 0.091, "fair_wp_decimal": 0.713, "confidence": "medium"}
  ]
}

Related sports API developer guides