# AGENTS.md — PinnFeed

Use with Cursor, Claude Code, Codex, Copilot. Full compact API: https://pinnfeed.io/llms-api.txt


Source of truth: https://pinnfeed.io/openapi.json · Docs: https://pinnfeed.io/docs · Skill: https://pinnfeed.io/SKILL.md · This file: https://pinnfeed.io/llms-api.txt · AGENTS.md: https://pinnfeed.io/AGENTS.md

Educational content for adults (18+). Odds data only — not a bookmaker; not affiliated with Pinnacle.

## Auth

Keys start with `ps_live_`. Create at https://pinnfeed.io/signup → dashboard (shown once).

```bash
export PINNFEED_KEY="ps_live_..."
```

Send **one of**: `x-api-key: $PINNFEED_KEY` · `Authorization: Bearer $PINNFEED_KEY` · `?key=$PINNFEED_KEY`

Never hardcode keys. Use `.env` + `.gitignore`. Revoke leaked keys in the dashboard.

## REST (https://pinnfeed.io)

| Method | Path | Notes |
|---|---|---|
| GET | /v1/account | Plan, limits, usage |
| GET | /v1/sports | Sports + live/prematch counts |
| GET | /v1/events | Fixtures (`sport`, `live`, `q`, `limit`) |
| GET | /v1/events/{id} | One event |
| GET | /v1/odds | Events + markets (`sport`, `market`, `main`, `live`, `limit`) |
| GET | /v1/drops | Biggest shortenings (`minutes`, `min_pct`) |
| GET | /v1/closing | Closing archive list (Builder+) |
| GET | /v1/closing/{eventId} | Closing for one event (Builder+) |

Sports slugs: soccer, tennis, basketball, hockey, american-football, baseball, rugby, mma, boxing, volleyball-handball, esports, golf, cricket.

Markets: moneyline, spread, total, team_total. `main=true` = primary lines.

```bash
curl -sS -H "x-api-key: $PINNFEED_KEY" \
  "https://pinnfeed.io/v1/odds?sport=soccer&main=true&limit=5"
```

## WebSocket (Builder+)

`wss://pinnfeed.io/v1/stream` — Free/Hobby → HTTP 403 `plan_lacks_ws`.

1. Connect with `x-api-key` (or `?key=`).
2. Receive `welcome`; send `subscribe` within ~30s.
3. Receive `subscribed` → chunked `snapshot` → `delta` batches.
4. Reply to `ping` with `pong` (~every 20s). Silent ~60s → close.

```json
{"type":"subscribe","sports":["soccer"],"markets":["moneyline","spread","total"],"main":true,"live":true}
```

## MCP (POST https://pinnfeed.io/mcp)

Streamable HTTP, JSON-RPC. Same key auth. Each tools/call = 1 REST request.

Tools: get_account, list_sports, search_events, get_live_odds, get_prematch_odds, get_event, get_drops, get_closing_odds.

Cursor `~/.cursor/mcp.json`:
```json
{"mcpServers":{"pinnfeed":{"url":"https://pinnfeed.io/mcp","headers":{"Authorization":"Bearer YOUR_KEY"}}}}
```

Claude Desktop / ChatGPT (no custom headers): `https://pinnfeed.io/mcp?key=YOUR_KEY`

Claude Code: `claude mcp add --transport http pinnfeed https://pinnfeed.io/mcp --header "Authorization: Bearer YOUR_KEY"`

## Plan limits (from product catalogue)

| Plan | EUR/mo | WS | REST | Sports | Notes |
|---|---|---|---|---|---|
| Free | 0 | No | 1/s, 1000/day, 30s delay | 2 | Main markets |
| Hobby | 29 | No | 2/s realtime | 3 | Main + fair |
| Builder | 99 | 3 conn | 10/s | 13 | All markets, closing — WS plan |
| Pro | 199 | 10 conn | 30/s | 13 | + raw frames |
| Enterprise | custom | custom | custom | 13 | Contact |

Paid: 3-day trial; card required; charged after day 3 unless cancelled. Crypto prepaid 1/3/12 mo from dashboard.

## Error codes (REST)

401 missing_key / invalid_key · 403 sport_not_in_plan / plan_lacks_ws / plan_lacks_history / plan_lacks_raw · 429 rate_limited / daily_quota / connection_limit · 400 invalid_filter · 404 not_found

## Claim wording (do not shorten)

As of 9 November 2026, Builder (€99/mo or €990/yr ≈ €82.50/mo annually; VAT incl.) was the lowest published price found for a live + prematch Pinnacle WebSocket on monthly or annual billing. Prematch-only WS can be cheaper (oddssea Prematch $59/mo). odds-api.io Solo+WS ≈ €118/mo monthly or ≈ €98.33/mo annual (tax-excl. list). Never write unqualified "cheapest". Never invent latency vs named competitors.

## Vibe coding

https://pinnfeed.io/vibe-coding · https://pinnfeed.io/quickstart · Postman: https://pinnfeed.io/postman/pinnfeed.postman_collection.json