Live exchange odds over SSE: a working client
A live stream keeps every price on your site current from one connection, usually within a fraction of a second of the market moving. This guide builds a complete client for the Diamond Exch API stream, including the parts most first versions get wrong: reconnecting without gaps and handling a planned reconnect.
Updated 2026-11-17
How the stream works
You open GET /v1/stream once. It sends each event in full as a snapshot, then ready, and from then on only what changes:
| Message | What to do |
|---|---|
| snapshot | Store the event in full |
| ready | Your copy is complete; show it |
| market-update | Replace that market with the one sent |
| market-remove | Drop the market; its result follows |
| event-update | Update the event's name, start or state |
| event-remove | Drop the event |
| result | Settle the market |
| reconnect | Reconnect now with your last id |
A complete Node client
// npm install eventsource
import { EventSource } from 'eventsource'
const BASE = 'https://api-sandbox.diamondexchapi.live'
const book = new Map() // event id -> event
const es = new EventSource(BASE + '/v1/stream?events=ev_a,ev_b', {
fetch: (url, init) => fetch(url, { ...init,
headers: { ...init.headers, 'X-API-Key': process.env.DIAMONDEXCHAPI_KEY } }),
})
const on = (name, fn) => es.addEventListener(name, (m) => fn(JSON.parse(m.data)))
on('snapshot', (ev) => book.set(ev.id, ev))
on('market-update', ({ event, market }) => {
const ev = book.get(event); if (!ev) return
const i = ev.markets.findIndex((x) => x.id === market.id)
i >= 0 ? (ev.markets[i] = market) : ev.markets.push(market) // replace, never merge
})
on('market-remove', ({ event, market }) => {
const ev = book.get(event); if (ev) ev.markets = ev.markets.filter((x) => x.id !== market)
})
on('event-remove', ({ id }) => book.delete(id))
on('result', (r) => settle(r))
// EventSource reconnects by itself and sends Last-Event-IDReconnecting without missing anything
Every message has an id. Reconnect with the last one in the Last-Event-ID header and you receive exactly what you missed, results included. If it is too old to resume you get fresh snapshots instead, so your copy is always whole. Browser-style EventSource clients send the header for you; with a raw HTTP client, send it yourself.
Planned reconnects
Streams do not stay open forever. A reconnect message arrives when a server restarts and on every stream after about 14 minutes. Act on the message itself: reconnect straight away with your last id rather than waiting for the connection to close.
Telling quiet from dead
A : heartbeat comment line arrives every 15 seconds. If you hear nothing at all for 45 seconds, reconnect. A Python client that does all of this:
# pip install requests sseclient-py
import json, os, requests, sseclient
URL = "https://api-sandbox.diamondexchapi.live/v1/stream?events=ev_a,ev_b"
headers = {"X-API-Key": os.environ["DIAMONDEXCHAPI_KEY"], "Accept": "text/event-stream"}
last_id, book = None, {}
while True:
if last_id:
headers["Last-Event-ID"] = last_id
try:
resp = requests.get(URL, headers=headers, stream=True, timeout=(10, 45))
for m in sseclient.SSEClient(resp).events():
last_id = m.id or last_id
if m.event == "reconnect":
break # reconnect now, with last_id
data = json.loads(m.data)
if m.event == "snapshot":
book[data["id"]] = data
elif m.event == "market-update":
upsert(book, data["event"], data["market"])
elif m.event == "event-remove":
book.pop(data["id"], None)
elif m.event == "result":
settle(data)
except requests.RequestException:
pass # network drop: loop and resumeFalling behind is safe
If your server is slow, you are not sent every tick you missed: you get the latest state of each market. There is never a backlog of stale prices to work through.
Sandbox and live
Sandbox keys open one stream at a time with up to 5 events, listed by id, and prices 60 seconds old. Live keys may use events=all, which also picks up events that start later. See the API reference.
Common questions
Why SSE and not WebSocket?
Odds flow one way, from us to you. SSE is plain HTTP, passes proxies and firewalls, and has resume built in through Last-Event-ID.
How many connections do I need?
One. A live key with events=all receives every event on your plan, including ones that start later.
Can a browser connect directly?
No. Keys only work from your servers' IP addresses. Your server keeps the stream and serves your own pages.