Skip to main content

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:
An empty channels array subscribes to all available channels. To subscribe to specific channels:
You can optionally enable reliable delivery with message acknowledgments:

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:
Respond with pong within 120 seconds or the connection is closed:
You can also send pings from the client — the server responds with pong.

Channels

Client-filtered channels

These channels only deliver data belonging to your clientName:

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:
When enabled, each data message carries requireAck: true, and you must acknowledge it so the server can release it from its buffer:
Or acknowledge a range in one message (recommended for throughput):
How it works:
  • The server buffers up to 100 unacknowledged messages per subscription and re-sends any not acked within 30 seconds.
  • seq is per-subscription and strictly increasing, so a gap in seq means you missed a message.
  • To recover missed messages after a reconnect, request a replay from the last seq you processed:
If you fall further behind than the 100-message buffer, the oldest unacked messages are dropped. Ack promptly (or use ack_batch) and treat any seq gap that a replay can’t fill as a signal to reconcile via the REST endpoints (GET /fixtures/orders, GET /fixtures/bets).

Changing subscriptions

Change channels without reconnecting:
The server replies with channels_updated.

Betslip subscriptions

The betslip channel pushes real-time odds for selections you’re watching. There are two ways to subscribe:
  1. Via REST — calling GET /fixtures/betslip registers a 60-second sliding window; each call resets the timer and immediately broadcasts a snapshot over the WebSocket.
  2. Via WebSocket — send a subscribe_betslip message with an explicit ttl (10–3600s) and bookmaker list for finer control, and unsubscribe_betslip to 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.
A maximum of 20 active betslip subscriptions per client (REST + WS combined, fixtures and futures together) is enforced. Message shapes and the 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

The betslip channel must be in your subscriptions (add it via login or update_channels) before subscribing.

subscribe_betslip

  • bookmakers must be a non-empty list.
  • ttl is 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).
Server confirms:
Bookmakers you have no account for are dropped from the subscription and returned in a 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 the orders table:

Bets / settlements

Full row from the bets 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 by fixtureId + outcomeId + playerId; a futures payload is keyed by futureId + futureOutcomeId + participantId and carries no playerId at all. Fixture:
Futures:
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.