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}
snapreplaces your copy.d: nullwithrev: 0means no data yet; a realsnapfollows once it exists.patchis a JSON Merge Patch: objects merge recursively,nulldeletes a key, and arrays are replaced whole.endis sent onoddsandpitchwhen the event finishes. The event'scoreturnsstate: "finished", and it leaves thelivetopic.
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).