Live stream
GET /v1/stream, the chain's market events as server-sent events, with exact replay.
GET /v1/stream sends a market event each time a pool trades or a token's chart moves.
An event carries no price: it is the signal to read the JSON routes again.
curl -sN 'https://api.blockhash.xyz/v1/stream?keys=0x0bd7d308f8e1639fab988df18a8011f41eacad73'The first events, as WETH traded:
event: hello
data: {"chainId":4663,"pollMs":500,"head":"460891976","cursor":"460891976"}
id: 460891976
retry: 3000
event: candle
data: {"seq":"460891998","kind":"candle","key":"0x0bd7d308f8e1639fab988df18a8011f41eacad73","revision":"116016312","payload":{"at":1794858553,"block":"116016312"},"at":"2026-11-16T19:49:14.225Z"}
id: 460891998Parameters
| Parameter | What it does |
|---|---|
kinds | Comma-separated event kinds: price, candle. |
keys | Comma-separated subjects: token addresses or pool ids. |
since | Resume after this sequence number. The Last-Event-ID header does the same. |
Filters change what is delivered, never your position.
Market events
Every block's swaps become one price event per pool that traded and one candle event per token whose chart moved, at most one a subject a second.
Each event's data is { seq, kind, key, revision, payload, at }, and its id is its seq.
| Kind | key | Meaning |
|---|---|---|
price | A pool id | The pool traded. payload is { block, at, swaps, tokens }: the newest block it traded in, that block's Unix time, how many of the block's swaps hit the pool, and the pool's two token addresses where they are known. revision is the block number. |
candle | A token address | A pool of the token traded, so its candles, detail and swaps changed. payload is { block, at }. |
Ignore a kind you do not know.
Control events
| Event | Meaning |
|---|---|
hello | The first event: { chainId, pollMs, head, cursor }, with retry: set. Its id is your cursor: the head for a fresh connection, or the id you resumed with. |
ping | Every 15 seconds. Its id is your safe checkpoint: every event below it was delivered to you or filtered out. |
resync | { floor, head, reason }, reason too-old, too-far or unknown. Your position could not be replayed, and the stream goes on from the head. |
bye | The stream closed, with its reason: max-age after 30 minutes, or more than 5,000 events waiting to be written to you. Reconnect from your checkpoint. |
Resuming
Reconnect with the Last-Event-ID header, or ?since=<seq>, and you receive exactly what you missed.
Resume from the last ping id or the last event id you processed.
A connection with no id starts at the head, so read your starting state once through the JSON routes.
An id older than 24 hours, more than 20,000 events behind the head, or unknown gets resync: read your state again.
Limits
| Limit | Answer |
|---|---|
| 4 open streams a key (12 a high-class key), 4 a client address without a key, and 500 in all | 429 too-many-streams, with Retry-After: 5 |
| A stream's life | 30 minutes, then bye with reason: "max-age" |
| The event log not answering | 503 unavailable or 503 store-unavailable, with Retry-After |