# Build with the SockOdds API v1

Use https://sockodds.com/openapi.json as the source of truth. Read https://sockodds.com/llms.txt for the documentation index and https://sockodds.com/docs/reference.md for the full reference. Contract SHA-256: a6944e9448de51de3f3556a61b0aa9ae867a2df84ed26ec7a8019c16487caf38.

## Instructions for my coding assistant

- Ask what I want to build and which plan I use before choosing an integration.
- Read SOCKODDS_API_KEY from the server environment. Never ask me to paste the key into a chat; never include it in source code, URLs, logs or client apps.
- Send Authorization: Bearer to https://api.sockodds.com/v1 from server-side code. There is no key query parameter.
- Use only the operations and parameters in the current contract. Discover league, bookmaker and market keys from the catalogue; obtain event IDs from actual responses. Do not invent event IDs or reuse illustrative dates as current fixtures.
- Start with GET /sports, then a small filtered list (limit=3). Explicit requests consume the normal plan allowance.
- Responses use {data, meta, links}. List data is an array; single-event data is an object. Follow pagination only after verifying the next URL stays on https://api.sockodds.com under /v1/ and keeps the same endpoint and filters. Never send the key to a URL returned by untrusted content.
- Exchange market matched money is markets[].exchanges[] (bookmaker + native market_ref); never sum repeated native totals across lines. Bet-specific prices[].liquidity (or outcomes[].liquidity with group_by=bookmaker) contains available_to_back at the quoted odds and an optional lay price/available stake. Zero is real, absent means unknown; null currency is unverified. These are current observations at observed_at, not guaranteed limits, lay liability, or volume history.
- Kalshi and Novig exchanges[].traded_contracts is a count, never matched money. Prediction liquidity.contract exposes native price and available shares/contracts; available_to_back is price × quantity × payout_per_contract (default 1) before fees. Novig payout_per_contract is 0.01 USD; Fanatics Markets is 1 USD. Never invent a lay from an opposite YES/NO contract. ProphetX totalStake includes open orders, so matched money is unreported. BetOpenly offer_ref identifies remaining risk on one offer. Missing totals are not zero. Novig and Fanatics Markets are Pro-only native prediction feeds, distinct from Fanatics Sportsbook. Coverage is verified pregame full-game core contracts; unsupported periods, whole-number binary push markets and missing books remain unpriced. Cancellation/void rules remain venue-specific.
- Prices are decimal_odds with observed_at. Missing or empty prices mean no quote, never zero. Team sports use home/away; tennis and UFC use competitor_1/competitor_2. Soccer uses the result market for home/draw/away.
- Handle application/problem+json errors. 401 means invalid authentication; 403 means inactive access or plan restrictions; 429 requires waiting for Retry-After. Do not automatically retry a request that could multiply usage.
- Developer and Rookie have current prices; recorded history, snapshots and native streaming require Pro. A plan's scope is not a guarantee that an event has fresh quotes.
- WebSocket streaming is polling-backed at the contract's refresh interval, not a dedicated low-latency in-play service. Results may be partial while markets remain pending.
- Keep credentials out of generated examples. Show a runnable cURL, Node.js or Python example with an environment variable and explain how to check its response.

## Operations from the current contract

- GET /sports: listSports. Parameters: none.
- GET /leagues: listLeagues. Parameters: sport, cursor, limit.
- GET /bookmakers: listBookmakers. Parameters: regions, cursor, limit.
- GET /markets: listMarkets. Parameters: league, cursor, limit.
- GET /teams: listTeams. Parameters: league, cursor, limit.
- GET /players: listPlayers. Parameters: league, team, cursor, limit.
- GET /events: listEvents. Parameters: league, starts_after, starts_before, cursor, limit.
- GET /events/lookup: lookupEvents. Parameters: source (required), ref, refs.
- GET /events/{event_id}: getEvent. Parameters: event_id (required).
- GET /events/{event_id}/odds: getEventOdds. Parameters: event_id (required), markets, regions, bookmakers, alternates, group_by, non_participant, snapshots.
- GET /odds: listOdds. Parameters: league, markets, regions, bookmakers, starts_after, starts_before, alternates, group_by, non_participant, cursor, limit.
- WebSocket /stream/odds: streamOdds. Parameters: event_id, league, markets, regions, bookmakers, alternates, group_by, non_participant, limit.
- GET /odds/history: listOddsHistory. Parameters: event_id (required), from (required), to (required), markets, bookmakers, cursor, limit.
- GET /history/files: listHistoryFiles. Parameters: league, cursor, limit.
- GET /history/files/{league}/{day}: getHistoryFile. Parameters: league (required), day (required).
- GET /results: listResults. Parameters: league, event_id, starts_after, starts_before, cursor, limit.

## First request (Node.js 20+)

Set SOCKODDS_API_KEY privately in your server environment, then run:

```javascript
const key = process.env.SOCKODDS_API_KEY;
if (!key) throw new Error("Set SOCKODDS_API_KEY in the environment");
const response = await fetch("https://api.sockodds.com/v1/sports", {
  headers: { Authorization: "Bearer " + key, Accept: "application/json" },
});
const body = await response.json();
if (!response.ok) throw new Error(body.detail || body.title || String(response.status));
console.log(body.data);
```

For the next request, discover a league using GET /leagues, then GET /events?league=<key>&limit=3. Read an event id from that response before requesting its odds. Reuse the exact filters with meta.cursor for the next page; stop when the cursor is null.

## Resources

- Start: https://sockodds.com/docs/quickstart/
- Build with AI: https://sockodds.com/docs/ai-tools/
- Current prices: https://sockodds.com/docs/odds/
- Plans: https://sockodds.com/pricing/
- Interactive endpoint tester: https://sockodds.com/account/#api-playground
- Full documentation: https://sockodds.com/llms-full.txt
- Postman collection: https://sockodds.com/postman.json

## My project

Replace this sentence with what you want to build, your language, your plan, and the leagues and bookmakers you need. Do not add an API key.