Endpoint
Connection flow
1. Connect
Open a WebSocket connection. No authentication is needed at connection time.2. Login
Send a login message within 30 seconds of connecting:channels array subscribes to all available channels. To subscribe to specific channels:
3. Login confirmation
On success, the server responds with:4. Receive updates
Data messages follow this format:
Full per-channel payload schemas are in Payload schemas below.
5. Keep alive
The server sends a ping every 30 seconds:Channels
Client-filtered channels
These channels only deliver data belonging to yourclientName:
Global channels
All subscribers receive these:Reliable delivery & acknowledgments
By default, messages are fire-and-forget — fast, but a message dropped during a disconnect is gone. Enable reliable delivery at login to get at-least-once delivery with acknowledgments and replay:data message carries requireAck: true, and you must acknowledge it so the server can release it from its buffer:
- The server buffers up to 100 unacknowledged messages per subscription and re-sends any not acked within 30 seconds.
seqis per-subscription and strictly increasing, so a gap inseqmeans you missed a message.- To recover missed messages after a reconnect, request a replay from the last
seqyou processed:
Changing subscriptions
Change channels without reconnecting:channels_updated.
Betslip subscriptions
Thebetslip channel pushes real-time odds for selections you’re watching. There are two ways to subscribe:
- Via REST — calling
GET /fixtures/betslipregisters a 60-second sliding window; each call resets the timer and immediately broadcasts a snapshot over the WebSocket. - Via WebSocket — send a
subscribe_betslipmessage with an explicitttl(10–3600s) and bookmaker list for finer control, andunsubscribe_betslipto cancel early.
Futures subscribe via REST only — and futures are off today.
GET /futures/betslip answers
501 until OddsPapi’s db-v2 identifier scheme is live, so no futures subscription can be registered
and no futures delta is published. When it turns on, that endpoint registers the same 60-second
sliding window and its deltas arrive on this channel; the subscribe_betslip /
unsubscribe_betslip WebSocket messages take fixtureId + outcomeId + playerId and have no
futures form, so holding a futures subscription open means re-calling GET /futures/betslip inside
each 60-second window.subscribed_betslip confirmation are documented in Betslip subscription messages below.
Example: Python client
Example: JavaScript client
Message types
Client → Server
Server → Client
Betslip subscription messages
Thebetslip channel must be in your subscriptions (add it via login or update_channels) before subscribing.
subscribe_betslip
bookmakersmust be a non-empty list.ttlis optional (seconds), clamped to 10–3600s; defaults to 60s if omitted.- Re-subscribing to the same selection refreshes the TTL and updates the bookmaker set (idempotent).
skipped array. A maximum of 20 active betslip subscriptions per client (REST + WS combined) is enforced.
unsubscribe_betslip
Payload schemas
Data messages wrap channel payloads in the envelope{type, channel, event, payload, ts, seq}. The orders, bets, and settlements channels deliver the full database row (row_to_json); balance, emergency, and betslip use custom shapes.
Orders
Full row from theorders table:
Bets / settlements
Full row from thebets table (the settlements channel uses the same shape):
Subscribing to both
bets and settlements delivers settlement updates twice — once on each channel. Use settlements alone if you want a dedicated settlement feed.Balance
Emergency
Betslip
Pushed while a betslip subscription is active. A fixture payload is keyed byfixtureId +
outcomeId + playerId; a futures payload is keyed by futureId + futureOutcomeId +
participantId and carries no playerId at all.
Fixture:
No futures delta is published today. The payload above is the shape futures deltas will take,
and the plumbing is in place —
GET /futures/betslip will register the same 60-second sliding
subscription as the fixture endpoint — but the whole /futures/* surface answers 501 until
OddsPapi’s db-v2 identifier scheme is live, so no futures subscription can exist and nothing is
broadcast on this channel for a future. Fixture betslip deltas are unaffected.The oddsId inside odds.{bookmaker} is opaque — store it and send it back verbatim. ABP
always publishes the key that actually matched.Connection limits
Next steps
Currency & Limits
How values are denominated and converted across currencies.
Errors
Handle error responses and decline reasons.