Skip to Content
API ReferenceSSE Stream

Unified Stream

GET /api/v1/stream — Real-time odds and opportunity updates via Server-Sent Events (SSE).

Requires WebSocket Add-on ($99/mo) on any paid tier, or Enterprise (included). Free tier does not support streaming.

AuthenticationPermalink for this section

Pass your API key via header or query parameter:

# Header (recommended for server-side) curl -H "X-API-Key: sk_live_your_key" \ https://api.sharpapi.io/api/v1/stream # Query param (required for browser EventSource) https://api.sharpapi.io/api/v1/stream?api_key=sk_live_your_key

Query ParametersPermalink for this section

ParameterTypeDefaultDescription
channelstringopportunitiesWhat to stream: odds, opportunities, gamestate (Enterprise only), or all
sportstringallFilter by sport(s), comma-separated (e.g. basketball, football, ice_hockey)
sportsbookstringtier-allowedFilter by sportsbook(s), comma-separated
leaguestringallFilter by league(s), comma-separated
eventstringallFilter by event ID(s), comma-separated
marketstringallFilter by market type(s), comma-separated (e.g. moneyline, point_spread, total_points, player_points)
min_evnumber2.0Minimum EV percentage for +EV opportunity events
min_profitnumber0.5Minimum profit percentage for arbitrage events only (does not apply to low-hold filtering)
statestringUS state code for sportsbook deep links in odds and opportunity events (e.g., nj, ny, il). Ensures deep_link URLs redirect to the correct state-specific sportsbook domain.
api_keystringAPI key (alternative to header auth for browser EventSource)

Channel OptionsPermalink for this section

ChannelEvents DeliveredUse Case
oddssnapshot, odds:update, odds:locked, odds:removed, heartbeatTrack odds movements
opportunitiessnapshot, ev:detected/expired, arb:detected/expired, middles:detected/expired, low_hold:detected/expired, heartbeatAlert on opportunities
gamestategamestate:snapshot, gamestate:update, gamestate:removed, heartbeatLive scores, periods, clocks, and situational data per event. Enterprise tier only. See Live Game State for the full field catalog.
allAll event typesFull real-time picture

Convenience RoutesPermalink for this section

RouteEquivalent To
GET /api/v1/stream/odds/api/v1/stream?channel=odds
GET /api/v1/stream/opportunities/api/v1/stream?channel=opportunities
GET /api/v1/stream/gamestate/api/v1/stream?channel=gamestate
GET /api/v1/stream/all/api/v1/stream?channel=all
GET /api/v1/stream/events/:eventId/api/v1/stream?channel=odds&event=:eventId

SSE Event TypesPermalink for this section

connectedPermalink for this section

Sent immediately when the stream is established.

event: connected data: {"stream_id":"stream_1704960637000","channel":"all","filters":{"sportsbook":null,"sport":["basketball"],"league":["nba"],"event":null,"market":null},"reconnected":false}
FieldTypeDescription
stream_idstringUnique stream identifier
channelstringEcho of requested channel (odds, opportunities, or all)
filtersobjectEcho of active filters
reconnectedbooleantrue if this is a reconnection via Last-Event-ID
trialobject | undefinedPresent if user is on a streaming trial. Contains active, expires_at, remaining_hours, max_streams

snapshotPermalink for this section

Full data dump sent after connected. Contains all current odds or opportunities matching your filters. Large datasets are chunked across multiple snapshot events (up to 1000 items each).

Each odds object in the snapshot contains all fields — this is the full Odds shape that your client should store locally. Subsequent odds:update events send only changed fields (see below).

event: snapshot id: evt_00001 data: {"odds":[{"id":"123456","sportsbook":"draftkings","event_id":"nba_phosuns_phi76ers_2026-02-08","sport":"basketball","league":"nba","home_team":"PHI 76ers","away_team":"PHO Suns","market_type":"moneyline","selection":"PHO Suns","selection_type":"away","odds_american":-155,"odds_decimal":1.645,"odds_probability":0.608,"line":null,"event_start_time":"2026-02-08T19:00:00Z","is_live":false,"timestamp":"2026-02-08T18:47:20Z","deep_link":"https://sportsbook.draftkings.com/event/..."}],"count":1000,"total":3200,"offset":0,"has_more":true}
FieldTypeDescription
oddsarrayArray of full Odds objects (see Odds endpoint for all fields)
countnumberNumber of odds in this chunk
totalnumberTotal number of odds matching filters
offsetnumberOffset of this chunk in the full result
has_morebooleantrue if more snapshot chunks follow

snapshot:completePermalink for this section

Signals all initial snapshots have been sent. Safe to hide loading states after receiving this.

event: snapshot:complete id: evt_00005 data: {"status":"ready","books":["draftkings","fanduel"],"total_odds":3200}

odds:updatePermalink for this section

Fired when odds change for a sportsbook. Only sent on odds or all channels.

Compact delta payload. Delta events contain only fields that can change between updates — id, odds_american, odds_decimal, odds_probability, line, is_live, and timestamp. Static fields like sportsbook, sport, league, home_team, away_team, market_type, selection, deep_link, and event_start_time are not included in deltas. Merge each delta into your local odds map by id using the full objects received in the initial snapshot. See Migration: Compact SSE Deltas below.

event: odds:update id: evt_00042 data: {"odds":[{"id":"123456","odds_american":-150,"odds_decimal":1.667,"odds_probability":0.6,"line":null,"is_live":false,"timestamp":"2026-02-08T18:47:38Z"}],"count":1,"book":"draftkings","partial":false}

Delta object fields (OddsDelta):

FieldTypeDescription
idstringUnique odds ID — matches the id from the initial snapshot
odds_americannumberUpdated American odds (e.g. -150)
odds_decimalnumberUpdated decimal odds (e.g. 1.667)
odds_probabilitynumberUpdated implied probability (e.g. 0.6)
linenumber | nullUpdated line/spread (e.g. -3.5), or null for moneyline
is_livebooleanWhether the event is currently live
is_activebooleantrue = market open/bettable; false = market suspended/closed with the price frozen. A market suspending (e.g. after a goal) emits an odds:update with is_active: false — grey out the line rather than trusting the frozen price. See also the odds:locked event.
is_main_linebooleantrue when this line is the consensus main line for its market; false for alternate lines. Can flip as the main line moves.
is_alternate_linebooleanPositive-polarity sibling of is_main_line (mutually exclusive).
is_stale_pregame_pricebooleantrue when a live row still carries a pre-game price that hasn’t moved since kickoff.
timestampstringISO 8601 time SharpAPI last refreshed this odd through its pipeline — advances every ingest cycle. A feed-freshness / liveness signal (matches OpticOdds’ timestamp); it is NOT when the price last changed. See understanding the timestamp field.

Exchange books additionally carry the dynamic volume, volume_24h, open_interest, and max_bet fields when present. Everything else — sportsbook, sport, league, home_team, away_team, market_type, selection, deep_link, event_start_time, and the nested entity refs — is static and comes from the initial snapshot; merge each delta into your local map by id and never read a static field off a delta.

Envelope fields:

FieldTypeDescription
oddsarrayArray of OddsDelta objects (compact — dynamic fields only)
countnumberNumber of odds in this chunk
bookstringSportsbook that changed (e.g. "draftkings")
partialbooleantrue if more chunks follow for this update batch

ev:detectedPermalink for this section

A new positive expected value opportunity has been found. Only sent on opportunities or all channels.

event: ev:detected id: evt_00043 data: [{"id":"a1b2c3d4e5f6","game_id":"nba_phosuns_phi76ers_2026-02-08","ev_percentage":4.35,"odds_american":-105,"odds_decimal":1.952,"no_vig_odds":-101,"selection":"PHO Suns -3.5","market":"point_spread","line":-3.5,"sportsbook":"draftkings","game":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","home_team":"PHI 76ers","away_team":"PHO Suns","start_time":"2026-02-08T19:00:00.000Z","is_live":false,"confidence_score":72,"kelly_percent":3.8,"book_count":4,"detected_at":"2026-02-08T18:47:20.000Z"}]

ev:expiredPermalink for this section

A previously detected +EV opportunity is no longer available.

event: ev:expired id: evt_00044 data: {"expired":["a1b2c3d4e5f6"],"timestamp":"2026-02-08T18:47:25.000Z"}

arb:detectedPermalink for this section

A new arbitrage opportunity has been found. Only sent on opportunities or all channels.

event: arb:detected id: evt_00045 data: [{"id":"61c501b83ce932d1","event_id":"nba_phosuns_phi76ers_2026-02-08","event_name":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","market_type":"moneyline","line":null,"profit_percent":2.8,"implied_total":97.2,"is_live":false,"legs":[{"sportsbook":"draftkings","selection":"PHO Suns","odds_american":150,"odds_decimal":2.5,"implied_probability":0.4,"stake_percent":41.4},{"sportsbook":"fanduel","selection":"PHI 76ers","odds_american":-130,"odds_decimal":1.769,"implied_probability":0.5652,"stake_percent":58.6}],"detected_at":"2026-02-08T18:47:21.000Z"}]

arb:expiredPermalink for this section

A previously detected arbitrage opportunity is no longer available.

event: arb:expired id: evt_00046 data: {"expired":["nba_celtics_lakers_2026-02-08_b3:moneyline:opp_a1b2c3"],"timestamp":"2026-01-26T02:10:39.500Z"}

middles:detectedPermalink for this section

A new middle opportunity has been found. Only sent on opportunities or all channels.

event: middles:detected id: evt_00047 data: [{"id":"middle_abc123","event_id":"nba_phosuns_phi76ers_2026-02-08","event_name":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","market_type":"player_points","side1":{"book":"draftkings","selection":"Over 22.5","line":22.5,"odds":{"american":-110,"decimal":1.909,"probability":0.5238,"fair_probability":0.51},"stake_percent":50,"odds_age_seconds":2.1,"deep_link":null},"side2":{"book":"fanduel","selection":"Under 23.5","line":23.5,"odds":{"american":-105,"decimal":1.952,"probability":0.5122,"fair_probability":0.49},"stake_percent":50,"odds_age_seconds":1.5,"deep_link":null},"middle_size":1,"middle_numbers":[23],"middle_probability":0.12,"expected_value":3.5,"quality_score":85,"detected_at":"2026-02-08T18:47:22.000Z"}]

middles:expiredPermalink for this section

A previously detected middle opportunity is no longer available.

event: middles:expired id: evt_00048 data: {"expired":["middle_abc123"]}

low_hold:detectedPermalink for this section

A new low-hold opportunity has been found. Only sent on opportunities or all channels.

event: low_hold:detected id: evt_00049 data: [{"id":"lowhold_abc123","event_id":"nba_phosuns_phi76ers_2026-02-08","event_name":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","market_type":"moneyline","line":null,"home_team":"PHI 76ers","away_team":"PHO Suns","start_time":"2026-02-08T19:00:00.000Z","hold_percentage":1.2,"is_live":false,"all_books":["draftkings","fanduel"],"side1":{"selection":"PHO Suns","books":["draftkings"],"line":null,"odds":{"american":-108,"decimal":1.926,"implied_probability":0.5192,"fair_probability":0.5096},"deep_links":{"draftkings":"https://sportsbook.draftkings.com/event/..."}},"side2":{"selection":"PHI 76ers","books":["fanduel"],"line":null,"odds":{"american":110,"decimal":2.1,"implied_probability":0.4762,"fair_probability":0.4904},"deep_links":{"fanduel":"https://sportsbook.fanduel.com/event/..."}},"detected_at":"2026-02-08T18:47:22.000Z"}]

low_hold:expiredPermalink for this section

A previously detected low-hold opportunity is no longer available.

event: low_hold:expired id: evt_00050 data: {"expired":["lowhold_abc123"]}

odds:lockedPermalink for this section

Fired when a market is suspended/closed (e.g. after a goal, during a line move, or a late-game lockout) — the price is frozen but the selection is no longer bettable. Carries the suspended subset of the current delta, same payload shape as odds:update, with is_active: false. Only sent on odds or all channels.

This is a 1:1 analogue of OpticOdds’ locked-odds for easy migration. It is supplementary — the same rows also arrive in odds:update with is_active: false, so clients that already read is_active need not subscribe to odds:locked separately. Use it when you want a dedicated lock signal without parsing every odds:update.

event: odds:locked id: evt_00052 data: {"odds":[{"id":"123456","odds_american":-2500,"is_live":true,"is_active":false,"timestamp":"2026-02-08T18:47:38Z"}],"count":1,"book":"pinnacle","partial":false}

A market re-opening emits a normal odds:update with is_active: true (and a fresh price). Markets a book removes entirely come through odds:removed instead.

odds:removedPermalink for this section

Odds removed by a sportsbook (e.g. market taken down, event settled). Only sent on odds or all channels.

event: odds:removed id: evt_00051 data: {"ids":["123456","789012"],"count":2,"book":"draftkings"}
FieldTypeDescription
idsstring[]Odds IDs to remove from local state
countnumberNumber of removed odds
bookstringSportsbook that removed the odds

heartbeatPermalink for this section

Keep-alive sent every 30 seconds. If you do not receive a heartbeat within 60 seconds, the connection may be stale.

event: heartbeat data: {"timestamp":"2026-01-26T02:11:07.846Z"}

errorPermalink for this section

Recoverable error on the stream. The connection remains open.

event: error data: {"code":"upstream_error","message":"Temporary issue fetching DraftKings data. Will retry."}

ReconnectionPermalink for this section

SSE supports automatic reconnection via the Last-Event-ID header. Each event includes an id field. When the client reconnects, the server delivers a fresh full snapshot — not a replay of individual missed events. This means your client receives a complete, up-to-date picture on every reconnect.

// Browsers handle this automatically with EventSource. // For custom clients, set the header on reconnect: const headers = { 'X-API-Key': 'YOUR_KEY', 'Last-Event-ID': 'evt_00042' };

On reconnect, clear your local state before processing the new snapshot. The connected event includes "reconnected": true so you can detect this. If you don’t clear state, stale odds from the previous session will mix with fresh data.

Browser EventSource handles Last-Event-ID and reconnection automatically. No extra code needed for the reconnect itself, but you must handle clearing state on the client side.

Code ExamplesPermalink for this section

// Local odds map — keyed by odds ID, stores full Odds objects from snapshot. // Delta events merge into this map by ID. const oddsMap = new Map(); const eventSource = new EventSource( 'https://api.sharpapi.io/api/v1/stream?channel=all&league=nba&api_key=YOUR_KEY' ); eventSource.addEventListener('connected', (e) => { const { stream_id, channel, reconnected } = JSON.parse(e.data); if (reconnected) oddsMap.clear(); // Fresh snapshot incoming console.log(`Stream ${stream_id} connected (${channel})`); }); eventSource.addEventListener('snapshot', (e) => { const { odds, count, total, has_more } = JSON.parse(e.data); // Store full Odds objects keyed by ID for (const odd of odds) { oddsMap.set(odd.id, odd); } console.log(`Snapshot chunk: ${count} odds (${oddsMap.size}/${total} total)`); }); eventSource.addEventListener('snapshot:complete', (e) => { console.log(`Snapshot complete: ${oddsMap.size} odds loaded`); }); eventSource.addEventListener('odds:update', (e) => { const { odds, book } = JSON.parse(e.data); // Merge compact deltas into local state — only dynamic fields are sent for (const delta of odds) { const existing = oddsMap.get(delta.id); if (existing) { Object.assign(existing, delta); // Merge changed fields } // If no existing entry, the odds appeared after our snapshot — wait for next snapshot } console.log(`${book}: ${odds.length} odds updated`); }); eventSource.addEventListener('odds:removed', (e) => { const { ids, book } = JSON.parse(e.data); for (const id of ids) { oddsMap.delete(id); } console.log(`${book}: ${ids.length} odds removed`); }); eventSource.addEventListener('ev:detected', (e) => { const opps = JSON.parse(e.data); opps.forEach(opp => console.log(`+EV: ${opp.selection} at ${opp.ev_percentage}%`)); }); eventSource.addEventListener('arb:detected', (e) => { const arbs = JSON.parse(e.data); arbs.forEach(arb => console.log(`Arb: ${arb.profit_percent}% profit`)); }); eventSource.addEventListener('middles:detected', (e) => { const middles = JSON.parse(e.data); middles.forEach(m => console.log(`Middle: ${m.event_name} — EV ${m.expected_value}%`)); }); eventSource.addEventListener('low_hold:detected', (e) => { const holds = JSON.parse(e.data); holds.forEach(h => console.log(`Low hold: ${h.hold_percentage}%`)); }); eventSource.addEventListener('heartbeat', () => { console.log('Connection alive'); }); eventSource.onerror = () => { console.log('Connection lost, auto-reconnecting...'); };

Concurrent Stream LimitsPermalink for this section

Each open SSE connection counts as one stream against your limit.

PlanMax Concurrent Streams
WebSocket Add-on ($99/mo)10
EnterpriseCustom

Exceeding your stream limit returns a 429 error with code too_many_streams. Close unused streams before opening new ones.

Managing StreamsPermalink for this section

  • Each unique GET /api/v1/stream connection counts as one stream
  • Closing the HTTP connection (or calling eventSource.close()) frees the slot immediately
  • Use broader filters on fewer streams rather than many narrow streams
  • The connected event payload includes your stream_id for tracking

Error HandlingPermalink for this section

Stream-Level ErrorsPermalink for this section

Errors sent as SSE events are recoverable — the connection stays open:

event: error data: {"code":"upstream_error","message":"Temporary issue fetching data. Will retry."}

Connection-Level ErrorsPermalink for this section

These close the connection. Handle them in onerror:

Error CodeHTTP StatusDescriptionResolution
too_many_streams429Too many concurrent streamsClose unused streams
tier_restricted403Streaming not available on your tierAdd WebSocket add-on
invalid_api_key401API key missing or invalidCheck your API key
validation_error400Invalid filter parametersCheck query params

Best PracticesPermalink for this section

  1. Use the right channelchannel=odds for odds only, channel=opportunities for opportunities only, channel=all for everything
  2. Use filters to reduce bandwidth — Pass sport, league, sportsbook, market, and event params to narrow data
  3. Set thresholds — Use min_ev and min_profit to filter out low-value opportunities server-side
  4. Wait for snapshot:complete — This signals all initial data has been sent. Hide loading states after receiving it
  5. Handle odds:removed — Remove odds from local state when received to avoid showing stale data
  6. Handle reconnection gracefullyEventSource auto-reconnects, but reset local state when you receive a new snapshot event
  7. Process updates asynchronously — Do not block the event handler; queue updates for background processing
  8. Monitor heartbeats — If no heartbeat arrives within 60 seconds, consider the connection stale and reconnect
  9. Close unused streams — Each open stream counts against your concurrent limit
  10. Use Last-Event-ID — Enables the server to replay missed events after a reconnection

Migration: Compact SSE DeltasPermalink for this section

Breaking change for SSE odds:update consumers. The odds:update event now sends compact OddsDelta objects containing only dynamic fields (id, odds_american, odds_decimal, odds_probability, line, is_live, timestamp). Static fields like sportsbook, sport, league, home_team, away_team, market_type, selection, deep_link, and event_start_time are only sent in the initial snapshot event.

Why: The previous payload sent the full Odds object on every change, producing ~170 KB/s per connection. The compact delta reduces bandwidth by ~5x, sending only the 6-7 fields that actually changed.

What to change in your client:

  1. Store snapshot odds in a local map keyed by id. The snapshot event still sends full Odds objects with all fields.

  2. Merge odds:update deltas by id instead of treating them as standalone objects. Each delta only contains the fields that can change — look up the full object in your local map and apply the update.

  3. Do not access static fields on delta objects. Fields like event_id, market_type, selection, home_team, and sportsbook are not present in deltas. Read them from your local map instead.

Before (broken — accessing fields not in delta):

eventSource.addEventListener('odds:update', (e) => { const { odds } = JSON.parse(e.data); for (const o of odds) { // ❌ o.event_id, o.market_type, o.selection are undefined in deltas console.log(`${o.event_id} ${o.market_type}: ${o.selection} → ${o.odds_american}`); } });

After (correct — merge into local state):

eventSource.addEventListener('odds:update', (e) => { const { odds } = JSON.parse(e.data); for (const delta of odds) { const full = oddsMap.get(delta.id); if (full) { Object.assign(full, delta); // Merge changed fields // ✅ full.event_id, full.market_type, full.selection are still available console.log(`${full.event_id} ${full.market_type}: ${full.selection} → ${full.odds_american}`); } } });
Last updated on