# SportWizzard

> The sports betting data API — real-time odds from 35+ books, players, teams, box-score stats, historical prices, and game context (weather, lineups, probable pitchers) in one canonical schema. Build your own models on it.

## Instructions for coding agents

- Base URL: `https://api.sportwizzard.com` — all endpoints under `/api/v1`, JSON envelope `{success, data, nextCursor, meta}`.
- Auth: `X-Api-Key: <api-key>` header, or `Authorization: Bearer <api-key>` — both accepted. Keys are self-serve at https://sportwizzard.com/account → API Keys tab (free, no card required).
- Credits: 1 credit = 1 event served in the response; historical endpoints ×5 per event; a snapshot pull is a flat 1 credit; empty responses and 304s are free. Billing enforcement is coming — everything is open today, but don't build automation that assumes that stays true.
- Bulk pulls: use `GET /api/v1/snapshot` (the entire live board, gzip, 1 credit flat) instead of paging `/odds` — then stay in sync with `GET /api/v1/odds/updated?since=` or ETag + `If-None-Match`.
- Don't poll `/api/v1/edges` or `/api/v1/arbitrage` faster than every 20s — the board doesn't refresh faster than that.
- Reference endpoints (`/leagues`, `/seasons`, `/sportsbooks`, `/teams`, `/players`, `/markets`, `/status`) are free and uncounted. Call `GET /api/v1/leagues` first — leagues are seasonal, and an out-of-season league returns a valid empty `data: []`.
- Machine-readable docs: [openapi.json](https://sportwizzard.com/openapi.json) · [llms-full.txt](https://sportwizzard.com/llms-full.txt) · [docs.md](https://sportwizzard.com/docs.md). Hosted MCP: `https://mcp.sportwizzard.com/mcp` (Streamable HTTP, `Authorization: Bearer <api-key>`).

SportWizzard is a REST API for sports betting data. It ingests odds from 35+ sportsbooks and DFS platforms (PrizePicks, Underdog, FanDuel, DraftKings, BetMGM, Pinnacle, and more) and normalizes everything into one canonical schema: events, odds, players, teams, box-score stats, historical prices, and per-game context (weather, lineups, probable pitchers, venue, scores). Pull the full live snapshot in a single gzip request, or query any slice to train and run your own models. DFS edges and cross-book arbitrage are included as derived-signal conveniences. Base URL: `https://api.sportwizzard.com`. All endpoints live under `/api/v1` and return JSON in a consistent envelope (`{success, data, nextCursor, meta}`). Authenticate with the `X-Api-Key` header (keys are issued via your account). Reference endpoints (leagues, sportsbooks, teams, players, markets) are free and uncounted. Lists use opaque cursor pagination via `nextCursor` → `?cursor=`.

## Docs

- [Getting Started](https://sportwizzard.com/developers): Base URL, authentication, response envelope, pagination, and freshness/caching.
- [Agent quickstart](https://sportwizzard.com/developers/agents): Copy-paste curl + MCP setup for Claude Code, Codex, and other AI agents.
- [Interactive API Reference](https://sportwizzard.com/developers/reference): Try all 28 v1 endpoints live.
- [Full documentation (markdown)](https://sportwizzard.com/llms-full.txt): Every endpoint with example requests and responses.
- [Single-file API doc (markdown)](https://sportwizzard.com/docs.md): Quickstart curl, endpoint index, credit costs, rate-limit etiquette, and MCP setup in one agent-consumable page.
- [OpenAPI specification](https://sportwizzard.com/openapi.json): Machine-readable OpenAPI 3 spec — the source of truth for the API.
- [AGENTS.md](https://sportwizzard.com/AGENTS.md): Agent-facing project guide (the cross-tool standard Codex and other agents read).
- [Hosted MCP server](https://mcp.sportwizzard.com/mcp): Streamable HTTP, bearer-key auth, no install — `claude mcp add --transport http sportwizzard https://mcp.sportwizzard.com/mcp --header "Authorization: Bearer sw_live_..."`. Also available as an [open-source stdio server](https://github.com/adamruehle/sportwizzard-mcp) (20 tools, mock mode) — install with `npx -y sportwizzard-mcp` ([npm](https://www.npmjs.com/package/sportwizzard-mcp)).

## Authentication

- Send your API key in the `X-Api-Key` request header. Example: `curl "https://api.sportwizzard.com/api/v1/events?league=mlb" -H "X-Api-Key: sw_live_..."`. `Authorization: Bearer <api_key>` is also accepted (MCP-client convention).
- Keys are created and managed at [your account](https://sportwizzard.com/account) under the API Keys tab.
- Reference endpoints require no key. All data endpoints are currently open (pre-billing) — a key is recommended but not yet enforced; don't assume that stays true.

## Leagues rotate — check before you assume "no data"

- Leagues are seasonal. `GET /api/v1/leagues` returns only leagues with an in-progress season right now — call it first. A league not in that list (e.g. `nba`/`nfl` outside their season) returns a **valid, empty** `data: []`, not an error — that means "out of season," not "broken." When that happens on `/odds`, `/events`, or `/edges`, the response's `meta.note` explains it automatically, e.g. `"No league in [nba] currently has an in-progress season... Active leagues right now: mlb, wnba, ..."` — no extra call needed to diagnose an empty result.

## Endpoints

- Events: `/api/v1/events` (filter by league/team/status/time), `/api/v1/events/{id}` (enriched detail — scores, result, venue, and `context` with weather, lineups, probable pitchers), `/api/v1/events/{id}/stats` (full box score — team + per-player stat blobs), `/api/v1/events/{id}/odds`, `/api/v1/events/active`
- Odds: `/api/v1/odds` (scope by league/sportsbook/market/event_id/player_id/team_id), `/api/v1/odds/updated?since=` (delta feed), `/api/v1/players/{id}/odds`, `/api/v1/teams/{id}/odds`
- Stats: `/api/v1/players/{id}/stats`, `/api/v1/teams/{id}/stats`, `/api/v1/stats/players` (bulk player box stats, filter by event_id/team_id/player_id, cursor-paginated)
- Snapshot: `/api/v1/snapshot` (the entire live board as one gzip blob, ETag + `If-None-Match` 304 support)
- Reference (free): `/api/v1/leagues`, `/api/v1/seasons?year=`, `/api/v1/sportsbooks`, `/api/v1/teams`, `/api/v1/players`, `/api/v1/markets`, `/api/v1/markets/active`, `/api/v1/status`
- Historical (paid plans, ×5 credits): `/api/v1/historical/odds`, `/api/v1/historical/arbitrage`
- Edges & Arbitrage (derived signals): `/api/v1/edges`, `/api/v1/arbitrage`
- Account: `/api/v1/account/usage` (your plan, rate limit, and monthly usage)

## Pricing

- [Pricing](https://sportwizzard.com/pricing): Free ($0, 5,000 credits/mo, 2 req/min), Pro ($25/mo, 500,000 credits, 10 req/min, historical ×5 credits), Growth ($50/mo, 1,500,000 credits, 30 req/min, snapshot 5-min refresh), Enterprise ($100/mo, soft-unlimited 5M fair-use, 60 req/min, real-time snapshot). 1 credit = 1 event served; empty responses and 304s are free. Annual billing = 2 months free.