# PinnWire setup instructions for AI agents

You are setting up access to PinnWire, a real-time Pinnacle sports odds API at https://pinnwire.com. Every step below is a read-only GET request. No account creation, no credentials to collect.

## Which key to use

- If the user gave you their PinnWire key (starts with `pk_`), use it.
- Otherwise use the public demo key: literally `key=demo` (10 req/min, 50/day — enough to explore).
- For their own free key (100/day, no card), the user visits https://pinnwire.com and enters their email — takes 5 seconds. Do not sign up for them.

## Step 1 — Verify the feed is live

    GET https://pinnwire.com/v1/health?key=demo

Expect `{"status":"ok", "events_in_store": <number>, ...}`.

## Step 2 — First odds call

    GET https://pinnwire.com/kit/v1/markets?sport_id=1&key=demo

Returns every live soccer event with decimal odds: `periods.num_0.money_line` (home/draw/away), `spreads`, `totals`, `team_total`.

## Reference

- sport_id: 1 Soccer, 2 Tennis, 3 Basketball, 4 Hockey, 5 Football, 6 Baseball, 7 Rugby, 8 MMA, 9 Boxing, 10 Volleyball/Handball, 11 Esports, 12 Golf, 13 Cricket
- Prematch: `&event_type=prematch`, or `/kit/v1/prematch/fixtures?sport_id=N`
- One event: `/kit/v1/details?event_id=N` · compact lines: `/kit/v1/prematch/lines?event_id=N`
- Player props & specials: add `&include_specials=1` (flat) or `nested` to markets/fixtures
- Incremental polling: pass the response's `last` back as `&since=`
- Price drops: `/api/drops?mode=live&min_drop_pct=5&key=KEY` — each drop includes `nvp`, the no-vig fair price; filters: max_drop_pct, markets, periods, live=1
- Rate limits: on HTTP 429, honor the `Retry-After` header
- FULL API reference (plain text, complete): https://pinnwire.com/llms-full.txt · human docs: https://pinnwire.com/docs.html · index: https://pinnwire.com/llms.txt

## Paid plans (for the user, not for you to purchase)

Stream $89/mo (SSE drop alerts + light REST) · Pro $89/mo (10 req/s) · Pro+Drops $139/mo (REST + SSE drop alerts) · Scale $219/mo (30 req/s) · Raw WebSocket firehose +$89/mo. Contact: sales@pinnwire.com.

Run steps 1–2, show the user a real odds response, and you are done.