Skip to Content
Blockhash Docs
Data API

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: 460891998

Parameters

ParameterWhat it does
kindsComma-separated event kinds: price, candle.
keysComma-separated subjects: token addresses or pool ids.
sinceResume 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.

KindkeyMeaning
priceA pool idThe 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.
candleA token addressA 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

EventMeaning
helloThe 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.
pingEvery 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.
byeThe 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

LimitAnswer
4 open streams a key (12 a high-class key), 4 a client address without a key, and 500 in all429 too-many-streams, with Retry-After: 5
A stream's life30 minutes, then bye with reason: "max-age"
The event log not answering503 unavailable or 503 store-unavailable, with Retry-After

On this page