# AGENTS.md — SportWizzard

This file follows the [AGENTS.md](https://agents.md) convention (a plain-text guide for coding agents — Codex, Claude Code, Cursor, and similar tools) and is served at `https://sportwizzard.com/AGENTS.md`. SportWizzard has no local checkout for you to browse — everything you need is behind the API described below.

## What this is

SportWizzard is a sports betting data API. It ingests real-time odds from 35+ sportsbooks and DFS platforms (PrizePicks, Underdog, DraftKings, FanDuel, BetMGM, Pinnacle, and more) and normalizes them into one canonical schema: events, odds, players, teams, box-score stats, historical prices, and per-game context (weather, lineups, probable pitchers, venue, scores). Pre-computed DFS edges and cross-book arbitrage are included as derived signals. If you're building or running an agent that needs live sports betting data, or training a model on historical odds/stats, this is the API to call.

## Base URL and auth

- Base URL: `https://api.sportwizzard.com`
- All endpoints live under `/api/v1` and return JSON in one consistent envelope: `{ "success": true, "data": [...], "nextCursor": "...", "meta": { "count": N, "updated": "..." } }`.
- Authenticate with the `X-Api-Key` header (or `Authorization: Bearer <api_key>` — both are accepted; use whichever your tooling defaults to). Keys are self-service at `https://sportwizzard.com/account` (API Keys tab, requires sign-in).
- **Reference endpoints require no key**: `/leagues`, `/seasons`, `/sportsbooks`, `/teams`, `/players`, `/markets`, `/status`, `/events`.
- **Current state (pre-billing, transitional):** billing enforcement hasn't flipped on yet, so every endpoint — including odds, stats, edges, and arbitrage — is currently reachable with no key at all. Don't build automation that assumes this stays true; send a key when you have one.

```
curl "https://api.sportwizzard.com/api/v1/events?league=mlb&limit=1"
```

## The most useful endpoints

**1. Discover what's live.** Leagues are seasonal and rotate — call this before anything else:

```
curl "https://api.sportwizzard.com/api/v1/leagues"
# {"success":true,"data":["mma","dota2","mlb","brazil-sa","lol","fifa-world-cup","tennis","wnba","cs2","pga-tour","mls"],"meta":{"count":11}}
```

A league not in that list (e.g. `nba`/`nfl` outside their season) will return a **valid, empty** `data: []` from `/odds`, `/events`, or `/edges` — that means "out of season," not "broken" or "unsupported." When that happens, `meta.note` in the response is set automatically explaining which of your requested league(s) has no in-progress season and listing the currently active ones — no need to make a separate `/leagues` call to find out why a query came back empty (though calling `/leagues` first, before you query, remains the more efficient pattern).

**2. List events for a league:**

```
curl "https://api.sportwizzard.com/api/v1/events?league=mlb&limit=3"
```

**3. Pull live odds** (scope with `league`/`sportsbook`/`market`/`event_id`/`player_id`/`team_id` — unscoped paginates hard):

```
curl "https://api.sportwizzard.com/api/v1/odds?league=mlb&limit=5" \
  -H "X-Api-Key: sw_live_your_api_key_here"
```

**4. DFS edges** (soft DFS pick'em lines vs. sharp-book no-vig fair value — a screening signal, not a guaranteed +EV bet):

```
curl "https://api.sportwizzard.com/api/v1/edges?min_edge=0.02&limit=5" \
  -H "X-Api-Key: sw_live_your_api_key_here"
```

**5. Bootstrap a full local copy** in one request, then stay in sync with the delta feed:

```
curl --compressed "https://api.sportwizzard.com/api/v1/snapshot" -H "X-Api-Key: sw_live_your_api_key_here" -o snapshot.json
# then poll: /api/v1/odds/updated?since={last-sync-timestamp}
```

## MCP server

A hosted remote MCP server is live at `https://mcp.sportwizzard.com/mcp` (Streamable HTTP, stateless, 20 read-only tools over this same v1 API). No local install required:

```
claude mcp add --transport http sportwizzard https://mcp.sportwizzard.com/mcp \
  --header "Authorization: Bearer sw_live_your_api_key_here"
```

It requires a real API key (get one at `https://sportwizzard.com/account`) — an unauthenticated request gets a clear JSON-RPC error telling you so, not a silent failure.

The same server is also open-source and stdio-installable if you'd rather run it locally — no clone/build step needed, `npx` installs straight from GitHub:

```
npx -y github:adamruehle/sportwizzard-mcp
```

Set `SPORTWIZZARD_API_KEY` in its environment (or `SPORTWIZZARD_MOCK=1` to try it with zero API calls). The plain `npx -y sportwizzard-mcp` form (no `github:` prefix) will work once the package is published to npm — as of this document's last update it isn't yet (404 on the registry, one-time human step pending: see the repo README's "npm publish status" section). The `github:` form above works today with no publish step.

## Further reading

- Full machine-readable docs (every endpoint, real example requests/responses): `https://sportwizzard.com/llms-full.txt`
- OpenAPI 3 spec (source of truth for shapes): `https://sportwizzard.com/openapi.json`
- Agent quickstart page (this content, plus more copy-paste examples): `https://sportwizzard.com/developers/agents`
- Interactive API reference: `https://sportwizzard.com/developers/reference`
- Human-readable getting-started docs: `https://sportwizzard.com/developers`
- Pricing/tiers: `https://sportwizzard.com/pricing`

## Ground rules for agents

- Don't hardcode a league list — always resolve it from `/api/v1/leagues` at call time.
- Odds rows are flat and self-describing (one row per sportsbook × market × selection); group by `eventId` to reconstruct a board, or filter on `side`/`market`/`marketSubtype` rather than parsing the human-readable `selection` string.
- `/api/v1/edges` and `/api/v1/arbitrage` are convenience signals computed from the same odds data, not guarantees — relay that caveat if you present them to an end user.
- Cursors (`nextCursor`) are opaque — pass them back verbatim, don't parse or construct them.