WebSocket protocol

wss://api.eventsfeed.dev/v1/stream

Authenticate on the upgrade request with Authorization: Bearer <key>, or ?key=<key> from a browser. The formal spec is the AsyncAPI document.

Topics

Topic Value
live Object eventId → Event with every live event. Events entering appear as new keys; leaving events are patched to null.
ev_…:core Event
ev_…:odds · :stats · :timeline · :pitch · :players That channel
ev_…:* Shorthand for all six channels of the event

Client → server

{"op":"sub","topics":["live","ev_k2m9x4q8zt:odds"]}
{"op":"sub","topics":["ev_k2m9x4q8zt:odds"],"since":{"ev_k2m9x4q8zt:odds":912}}
{"op":"unsub","topics":["ev_k2m9x4q8zt:odds"]}
{"op":"ping","id":1}

Server → client

{"t":"hello","connId":"…","limits":{"requestsPerHour":50000,"websockets":3},"heartbeatSec":30}
{"t":"ack","op":"sub","topics":["live","ev_k2m9x4q8zt:odds"]}
{"t":"snap","topic":"ev_k2m9x4q8zt:odds","rev":912,"d":{"markets":{…}}}
{"t":"patch","topic":"ev_k2m9x4q8zt:odds","rev":913,"d":{"markets":{"match_result.ft":{"selections":{"away":4.33}}}}}
{"t":"patch","topic":"live","rev":18343,"d":{"ev_k2m9x4q8zt":{"score":{"home":3}}}}
{"t":"end","topic":"ev_k2m9x4q8zt:odds","rev":2040}
{"t":"err","code":"rate_limited","msg":"…","retryAfterSec":120}
{"t":"pong","id":1}

Ordering and gaps

Per topic, revisions arrive in order and without gaps. If the server detects that it could not deliver a revision, it sends a fresh snap instead. You should still check rev on your side.

Reconnecting without losing anything

Keep the last rev per topic. After a reconnect, subscribe with since:

{"op":"sub","topics":["live","ev_x:odds"],"since":{"live":18343,"ev_x:odds":913}}

The server replays the patches you missed (it keeps the last ~200 per topic). If it no longer has them, you get a snap.

Heartbeat

The server pings every 30 s at the protocol level (standard WebSocket ping/pong, automatic in most clients). A connection that misses pings for ~90 s is dropped and frees its slot. You may also send {"op":"ping"} for an application-level round trip.

Reconnect policy

Use exponential backoff with jitter (1 s, 2 s, 4 s… capped at 30 s). Do not reconnect on close code 4001 (revoked key).