Delta Feed - New Version
We introduce a few changes that need to be considered in the new odds feed version which will become the main feed in the future.
Changes:
New & Deprecated Fields
New Fields
UpdateSequence - Incremental sequence number for each delta message of an event
LastUpdatedTime - Unix timestamp in seconds
Deprecated Field
Version - Previously used as a recovery identifier. Now replaced by UpdateSequence and LastUpdatedTime. The old recovery logic required to reconnect using the last received version. This field is now deprecated.
New Recovery Logic
Every delta now contains LastUpdatedTime, which acts as the recovery marker.
When reconnecting, its required to send the latest processed value: revision={LastUpdatedTime}
Odds88 will resend all missed updates from that timestamp to ensure catching up to the latest event state.
Initial Connection
For the first-time connection, the revision parameter is optional. However, we recommend sending a Unix timestamp for the last 1 hour to reduce load on both sides:
Prevents returning excessive historical data
Ensures smoother bootstrapping process
UpdateSequence Behaviour & Requirements
UpdateSequence increments by 1 for every delta message of single event. Expected Behaviour:
If the last received value is 12, the next should be 13
Duplicate values may rarely occur and should be accepted: e.g. 12, and next message again 12 which should be reprocessed.
Missing Update Detection
If there was a gap in the update sequence (e.g., 12 → 15) and the last received message was not a snapshot (type=6) it indicates that some deltas might have been missed and full event snapshot request from the API is required.
Recovery Stream Behaviour
During recovery:
The first recovery message is typically type=6 (EventSnapshotDelta)
Its required to drop deltas with an UpdateSequence lower than stored value
Example 1: Stored sequence = 10 During recovery the first received message is: UpdateSequence = 15, type = 6 This is acceptable - its a snapshot and event snapshot from API is not required. Example 2: Stored sequence = 10 The first received message is for an event is: UpdateSequence = 15, type = 3 This is not acceptable - not a snapshot and it is required to request event snapshot from API. Example 3: Event is missing from storage and the first received message for missing event is: UpdateSequence = 15, type = 3 This is not acceptable - not a snapshot and it is required to request event snapshot from API.
If event is missing from storage but event snapshot was received during recovery then API request is not needed.
Heartbeat Support
The new endpoint supports heartbeat messages so it's possible to differentiate idle periods from technical issues.
Heartbeat Timing
Heartbeat every 10 seconds
Expected flow: Delta or Heartbeat message
Connection Timeout Rules If there is no delta or heartbeat messages received for 30 seconds then it's required to close current connection and reconnect using LastUpdatedTime from last processed message. Our system closes stale connections automatically.
Message Wrapper Structure
All messages (deltas or heartbeats) are wrapped in the following structure:
Delta Structure
The Delta message has a common structure that applies to all types:
Summary
On Connection
Send revision=<LastUpdatedTime> - it is optional but recommended for first connection.
While connected
Track UpdateSequence per event.
Detect gaps and missing updates, then call snapshot API.
Handle heartbeat logic.
Reconnect after 30 seconds of inactivity.
Request snapshot from API only when required.
During Recovery
Drop messages with lower UpdateSequence.
Data Elements
Every event consists of 4 data elements. eventInfo - basic information about the event. markets - contains data about markets, selection and odds values. scoreboard - contains data about periods and score. betCancellations - contains data about the time period in which bets placed on specific markets should be cancelled.
Every data element has a dedicated delta type that is used to send updates for this specific element. Two exceptions are eventSnapshotDelta (type6), which contains all data elements, and eventStatusChangedDelta (type 1), which is used to update status and tradingStatus that are located inside eventInfo.
Data Storage Recommendations
Recommended approach of storing data for events is following. eventInfo should be stored in a document database like MongoDB. markets, scoreboard, betCancellation data is stored in a cache like Redis. This allows for time critical data of markets/odds to be processed and forwarded to frontend as fast as it is possible.
Establishing Connection
After receiving credentials from TIS, the next step is to establish connection with Odds88 WebSocket delta feed. We recommend doing initial connection with Unix timestamp for the last 1 hour to reduce load on both sides as it prevents returning excessive historical data. After that you should connect with Unix timestamp from last processed message.
Storing Data
Subscribing with revision = 0 will generate snapshots (type 6 delta) for all events active in a Odds88 system. This type of delta contains full data about an event and includes all 4 data elements. If an event doesn’t exist in the your database, it should be created. If an event exists all data elements that changed should be updated.
Upon receiving delta of type 2 a new event should be created in your DB. If an event already exists, changed fields should be updated. Deltas of type 2 and 6 are the only two deltas that should create new events in your database.
Next step is to process every other delta type that contains only updates for already existing events and update changed fields/properties in the database/cache for further use in your system/frontend solution. Structure of all delta types can be checked in swagger.
Events can have from 0 to many markets.
Markets can have from 1 to many selections.
After message processing is implemented, you can populate your database by connecting to feed. We recommend sending a Unix timestamp for the last 1 hour to reduce load on both sides. In case of reconnection it should happen with revision={LastUpdatedTime}. Existing data should be enough to create frontend views of sports, leagues and events.
To process messages it is required to use a multithreaded solution. Number of messages and their size can be significant during peak hours for a single threaded solution to handle the volume.
It is recommended to use MongoDB + Redis, for quick and reliable forwarding of data to frontend.
Last updated