.mjs or "type": "module"). Install ws with npm install ws; keep THERUNDOWN_API_KEY in the server environment and relay browser updates through your authenticated backend.
Step 1: Fetch the Sports List
Start by loading the list of available sports. This endpoint is public and does not require authentication.Step 2: Fetch Events for a Sport and Date
Once the user selects a sport, fetch events for that sport on a given date. Includemarket_ids=1,2,3 for moneyline, spread, and total. Use main_line=true to get only the primary line for each market.
These examples use the current UTC date and omit
offset, so the event day starts at midnight UTC. For a different market-day boundary, choose a date for that boundary and its matching offset.Step 3: Discover Available Markets
Not every sport or event has the same markets. Before building your odds columns, check which markets actually have data. There are two ways to do this:By sport and date
Returns all markets with active pricing for a sport on a given date, keyed by sport ID. Usehide_closed_markets=1 to exclude markets that have been taken off the board.
By event ID
Returns only the markets available for a specific event. Useful when building a detail view for a single game.event_id value returned by GET /api/v2/sports/{sportID}/events/{date} when calling per-event V2 endpoints.
Each market object includes:
The three core markets for an odds screen are 1 (Moneyline), 2 (Spread), and 3 (Total). See Market IDs for the full list including player props and live markets.
Step 4: Parse Markets for Display
Each event contains amarkets array. Index it by market_id to pull moneyline (1), spread (2), and total (3) for each sportsbook.
Join each team’s team_id to a TYPE_TEAM participant’s id; their display names can differ. Totals use TYPE_RESULT participants: ID 9 is Over and 10 is Under. Select a line carrying the requested affiliate’s quote, since books can have different main lines.
Step 5: Connect WebSocket for Real-Time Updates
Once your initial data is loaded, connect a server-side V2 Markets WebSocket client to receive live price updates. WebSocket access requires an Ultra plan or higher. Native browser WebSocket clients cannot set the authentication header, so browser consumers should connect through an authenticated backend relay. Filter by sport to reduce traffic. The Python example useswebsockets>=14; the Node.js example requires ws (npm install ws).
Step 6: Handle Price Updates in the UI
For each current V2market_price frame, merge it only into the matching quote already loaded from REST. The V2 data.id is the persisted price ID also present on that REST quote; match it within the event and affiliate. Update the existing quote object so its line and other REST metadata stay intact. Skip unknown IDs here; snapshot or discovery handling is separate. A non-empty closed_at marks the quote closed; an omitted, null, or empty closed_at means it is open.
Tips for Production
Use delta endpoints for efficient polling as a fallback
Use delta endpoints for efficient polling as a fallback
If the WebSocket disconnects, use
GET /api/v2/delta to fetch event deltas or GET /api/v2/markets/delta to fetch market price deltas since your last request. This is much more efficient than refetching the full event list.Animate price changes
Animate price changes
When a price moves, briefly highlight the cell green (price improved for the bettor) or red (price worsened). This visual cue helps users notice live movement.
Handle the 0.0001 sentinel value
Handle the 0.0001 sentinel value
Always check for
0.0001 before displaying a price. Show “Off Board” or “N/A” instead. See Sentinel Values for details.Cache the sports and affiliates lists
Cache the sports and affiliates lists
The sports and affiliates endpoints return reference data that rarely changes. Cache these responses and refresh once per day to avoid unnecessary API calls.
Filter aggressively
Filter aggressively
Use
affiliate_ids, market_ids, and main_line=true to reduce payload size. Only request the data your UI actually displays.Next Steps
WebSocket Streaming
Deep dive into WebSocket configuration
Efficient Polling
Delta endpoints and cache strategies for when WebSocket isn’t available
Player Props
Add player prop markets to your screen
Historical Odds
Track line movement over time
Data Model
How events, markets, lines, and prices relate
Sportsbook IDs
Full list of affiliate IDs