1. State: snapshot plus stream
- Connect the WebSocket first, then fetch the REST snapshot and merge it in. Per key, the newer
changedAtwins. - Store odds keyed by
oddsId. The key is the same on REST, WebSocket, history and settlement, so one store serves all four. - Log in with
sportIds,tournamentIdsandbookmakersfilters for what you trade. Smaller streams are faster to process and less likely to hit backpressure. - Pick a
receiveType.zstdcutsoddstraffic to roughly a fifth or sixth of JSON with a one-line decode.
2. Reconnect and resume
- Persist
serverEpochand the last processedentryIdper channel. - On reconnect, log in with
serverEpochandlastSeenId, and wait forresume_complete. - Handle
snapshot_required: re-fetch the REST snapshot for the listed channels, clear their cursors, keep consuming. - Act on the
reconnectcontrol frame as soon as it arrives. We send it before every release, so do not wait for the socket to close. - Reconnect on close codes
1006and1011with a short backoff. Treat4002(backpressure) and4003(too many connections) as problems to fix, not to retry blindly.
resumeWindowMs that ends in a snapshot. Time the second one. It is your worst-case recovery.
Detail: Resume & Replay, Troubleshooting.
3. Bookmaker staleness
- Subscribe to the
bookmakerschannel alongsideodds. - Keep
staleOddsperfixtureId:bookmakerpair and check it before you act on a price. - When it is
true, pause that bookmaker on that fixture, or fall back to another book. Resume when it returns tofalse. - Keep it apart from
suspended,activeandmarketActive. Those are the bookmaker’s own stops.staleOddsis about our view of the bookmaker. - Expect a book-wide incident as one message per fixture, not as a single message.
4. Rate limits and connections
- Odds endpoints allow 10 requests per second per
apiKey. All other endpoints allow 200 per minute. - Read
X-RateLimit-Remainingand back off on429for the time inRetry-After. - Use REST for snapshots and backfills, and the stream for changes. Polling odds in a loop is the usual cause of rate-limit trouble.
- Stay within 8 concurrent WebSocket connections per
apiKeygroup. Ask us before you design for more.
5. Monitoring
- Track the delivery hop: your receipt time minus the message
ts. Run NTP, or sub-100 ms readings mean little. - Track observation delay per bookmaker:
changedAt − bookmakerChangedAt, and compare it tomaxDelayLiveInSecandmaxDelayPregameInSecfromGET /bookmakers. - Alert on reconnect count,
snapshot_requiredcount, and the share of fixtures flaggedstaleOddsper bookmaker. - Subscribe to the status page for incidents and maintenance.
- Deploy close to us if latency matters: central Germany or US East.
6. Changes and support
- Follow the changelog. Entries tagged Breaking need action on your side.
- Ignore unknown fields in responses. New fields can appear in any release.
- Send the key in the
X-API-Keyheader rather than the query string, so it stays out of URLs and logs. - When you report an issue to contact@55-tech.com, include the affected channels or endpoints, UTC timestamps, and your
serverEpochandentryIdvalues.
Ready when
- A forced disconnect resumes with no gap, and a long one recovers through a snapshot in a time you have measured.
- A
staleOddsflag stops trading on that bookmaker and fixture without anyone stepping in. - A
429slows your client down instead of breaking it. - Your own dashboards show delivery hop, observation delay and stale share per bookmaker.