توثيق API

البدء السريع

احصل على أول إشارة edge خلال 30 ثانية. ولمعرفة خلفية النماذج والمنهجية اقرأ الورقة البحثية. research paper.

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

// Signal: NCAAMB, Purdue (away), fair_wp=0.74, market_ask=0.63, edge=+11c
// Action: BUY Purdue at 63c. Model says it's worth 74c. Hold to settlement.

import requests

resp = requests.get(
    "https://zenhodl.net/v1/edges",
    headers={"X-API-Key": "sk_live_YOUR_KEY"},
    params={"min_edge": 8}
)
for signal in resp.json()["signals"]:
    print(f"{signal['sport']} {signal['team']}: "
          f"fair={signal['fair_wp']:.0%} ask={signal['market_ask']:.0%} "
          f"edge=+{signal['edge']*100:.1f}c ({signal['confidence']})")

أي endpoint يجب أن أستخدم؟

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();

Get your API key at /signup (free tier) or /pricing (paid plans). Keys start with sk_live_. Keep it secret — treat it like a password.

Rate Limits

Rate limits are per-minute. Every response includes these headers:

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)."}

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", "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": "high",
    "is_score_change": false,
    "last_updated": "2026-03-22T19:29:55Z"
  }]
}

Response fields

GET /v1/edges

Current edge signals — only games where the model disagrees with the market by at least min_edge. This is the "actionable trades" endpoint.

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,
  "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,
    "period": 2,
    "seconds_remaining": 480.0,
    "score": "52-44",
    "confidence": "high",
    "is_score_change": false,
    "timestamp": "2026-03-22T19:29:55Z"
  }]
}

Response fields

GET /v1/sports

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

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

Real-time WebSocket stream. Updates every 5 seconds via WebSocket push.

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": "high"
}}

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.

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"  +EV at {venue}: edge={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},
      "Kalshi": {"home_ask": 0.63, "home_edge": 0.09},
      "DraftKings": {"home_ml": "-150", "home_implied": 0.60, "home_edge": 0.12},
      "FanDuel": {"home_ml": "-165", "home_implied": 0.623, "home_edge": 0.097}
    },
    "best_home_venue": "DraftKings"
  }]
}

GET /v1/predict/{sport}/pregame

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

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.

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.

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": 10000,
  "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, "beat_pct": 64.3}],
  "by_edge_bucket": [{"bucket": "8-12c", "count": 85, "avg_clv_c": 2.1, "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

Push notifications when edge signals are detected. Register a URL and receive a signed POST request in real-time — no polling needed. 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

All prediction endpoints now include confidence_interval — calibrated prediction bands from conformal prediction tables. Use these to assess uncertainty and size positions appropriately.

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

Width narrows as games progress (more data = more certainty). Early game: 10-15c width. Late game: 3-5c width.

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,
  "note": "Delayed 15 min. Upgrade for real-time across 7 sports.",
  "signals": [
    {"sport": "NBA", "team": "NY", "edge": 11.2, "fair_wp": 78.5, "confidence": "high"},
    {"sport": "NHL", "team": "BOS", "edge": 9.1, "fair_wp": 71.3, "confidence": "medium"}
  ]
}