# Pinnacle Odds API

> Real-time live and prematch sports odds from Pinnacle's MQTT WebSocket broker. Sub-second latency with Server-Sent Events streams for instant odds-drop alerts. Drop-in compatible with common third-party Pinnacle API formats — swap base URL + API key in existing client code.

This is a paid API service. Get a free trial key in seconds at https://pinnapi.com/ — no card, no email verification, your API key is your login.

The trial covers everything except SSE drop streams (capped at 100 REST requests/day). Paid plans start at $99/mo.

## For AI assistants integrating this API

- [Full API reference, LLM-optimized](https://pinnapi.com/llms-full.txt): Every endpoint, parameter, response shape, and code example as plain markdown in a single file. Fetch this first.

## Documentation

- [Full HTML docs](https://pinnapi.com/docs): Human-readable browser version with tabs and syntax highlighting
- [Landing page & pricing](https://pinnapi.com/): Plans, sign-up, comparison
- [User dashboard](https://pinnapi.com/panel): Manage subscription, view usage charts

## REST endpoints

Auth: `x-portal-apikey: YOUR_KEY` header or `?key=YOUR_KEY` query parameter.

- [GET /kit/v1/markets](https://pinnapi.com/docs#markets): Live or prematch markets for a sport. Pass `event_type=prematch` to switch feeds; defaults to live.
- [GET /kit/v1/details](https://pinnapi.com/docs#details): Single event by event_id (live store)
- [GET /kit/v1/prematch/fixtures](https://pinnapi.com/docs#prematch-fixtures): All prematch fixtures for a sport with full markets envelope
- [GET /kit/v1/prematch/markets](https://pinnapi.com/docs#prematch-markets): Markets for one prematch event by event_id
- [GET /kit/v1/prematch/lines](https://pinnapi.com/docs#prematch-lines): Compact line view for one prematch event
- [GET /api/drops](https://pinnapi.com/docs#api-drops): Queryable buffer of recent dropping odds. Pass `mode=live|prematch`
- [GET /health](https://pinnapi.com/docs#health): Service status, returns event counts and SSE client counts
- [GET /ping](https://pinnapi.com/docs#ping): Public liveness probe, no auth required

## SSE push streams

Auth: `?token=YOUR_TOKEN` (legacy) OR `?key=YOUR_API_KEY` (paid plan with `features.sse: true`).

- [SSE /odds-drop](https://pinnapi.com/docs#sse-live): Push stream of live odds drops, ~200ms latency. Optional `?min_drop=N` to pick the drop threshold (default 5%, floor 1%, no upper cap). **Cap: 1 connection per account on this endpoint** — opening a 2nd evicts the 1st. Email info@pinnapi.com to raise the cap.
- [SSE /odds-drop-prematch](https://pinnapi.com/docs#sse-prematch): Push stream of prematch odds drops. Optional `?min_drop=N` (same as live) and `?recheck=N` (hold N seconds + re-verify). Same 1-connection-per-account cap as `/odds-drop`. Counted independently — you can run one live + one prematch in parallel.

## Reference data

- [Sport IDs](https://pinnapi.com/docs#sport-ids): Soccer=1, Tennis=2, Basketball=3, Hockey=4, Football=5, Baseball=6, Rugby=7, MMA=8, Boxing=9, Other=10 (Volleyball/Handball), Esports=11, Golf=12 (moneyline-only)
- [Market types](https://pinnapi.com/docs#market-types): money_line, spreads, totals, team_total
- [Event response shape](https://pinnapi.com/docs#event-shape): periods.num_0 (full match), num_1 (1st half), num_2 (2nd half), etc.
- [Live game-state object](https://pinnapi.com/docs#live-state): `state` field on live events with in-game data passed through from Pinnacle (Soccer: score/redCards/yellowCards/corners/minutes; Basketball: scoreByQuarter/quarter/timeRemainingInQtr; Tennis: setsWon/gamesBySet/points/serving). REST only — not on SSE.
- [Affiliate program](https://pinnapi.com/docs#affiliate): Every account gets a unique `?ref=<code>` link visible in the dashboard. Refer paying customers, earn 30% of every payment lifetime. Tracked in panel, manual payouts at $50+ unpaid balance.
- [Rate limits](https://pinnapi.com/docs#ratelimits): Trial 100/day; Stream 100/day; Pro 10 req/sec; Pro+SSE 10 req/sec; Scale 30 req/sec

## Plans

- Trial: free, 100 reqs/day, no SSE
- Stream: $99/mo, drops-only SSE, REST limited
- Pro: $99/mo, REST 10 req/sec, no SSE
- Pro+SSE: $149/mo, REST 10 req/sec + SSE drops bundle (best value)
- Scale: $229/mo, REST 30 req/sec + SSE