How an odds feed API works, from snapshot to settlement

A sportsbook screen looks static: a list of matches, a column of prices. Underneath, an odds feed is a stream of thousands of small changes, and the operator’s job is to apply every one of them in the right order. This guide walks through that stream from the first request to the settled bet.

1. The data model

Almost every feed uses the same hierarchy:

• Sport: football, tennis, esports.
• Tournament or league: Premier League, ATP Tokyo, League of Legends Worlds.
• Event: one match, with a start time and participants.
• Market: one question about the event, such as 1X2, over/under 2.5 goals or map handicap.
• Outcome: one answer, with a price and a status (active, suspended, settled).

Every element has a stable identifier. Most integration bugs come from treating names as identifiers: team names change spelling, IDs do not.

2. Snapshot, then deltas

On start-up the client asks for a snapshot: the complete current state. From then on it receives deltas, small messages that say “this price moved”, “this market is suspended”, “this event started”.

Good feeds number their deltas. Nocturn Sport, for example, describes its feed as a full snapshot plus versioned deltas. If the client holds version N and receives N+2, it knows a message was lost and reloads instead of displaying a stale price. Feeds without versions force the client to guess, and guessing is how books end up offering yesterday’s odds.

3. Push and pull

Live football can change price several times a minute, so live feeds usually push messages over a persistent connection. Pre-match prices move slowly enough that pulling them over HTTP every few seconds is often fine. Many operators run both: pull for the pre-match catalogue, push for in-play.

4. Suspensions

A suspension is the feed saying “do not take bets on this right now”. Triggers include a goal, a penalty, a break of serve, a map ending, or the supplier losing its own data source. The client must apply suspensions faster than anything else; a price accepted during the seconds after a goal is the classic way to lose money.

Pre-match markets also close before kick-off. Nocturn Sport, for instance, closes them one minute before the start.

5. Placing the bet

If the API goes beyond publishing prices, bet placement follows a pattern:

1. The client sends the selection, the price it displayed and the stake, with a unique request ID.
2. The server checks that the price is still valid and the market open.
3. It accepts, rejects, or offers a new price.
4. If the network fails, the client resends with the same request ID, and the server returns the original answer instead of creating a second bet.

That last step, idempotency, protects both the player’s balance and the operator’s books.

6. Settlement

When the event ends, the feed publishes results per outcome: won, lost, void, or half-won and half-lost for split lines such as Asian handicaps. The platform settles each bet against them. Corrections happen: a result can be amended after review, so a settlement process must be able to re-settle cleanly.

7. What to test before going live

• Kill the connection mid-match and check the recovery.
• Replay a delta out of order and check the client notices.
• Place the same bet twice with one request ID.
• Settle an accumulator where one leg is void.

A feed that survives those four tests is ready for a Saturday afternoon.