Streaming

hb.stream.trades() delivers live Polymarket trades over a WebSocket. It handles the connection, subscription, and reconnection for you — you just iterate.

Install the streaming extra

Streaming needs a WebSocket dependency (the REST client doesn't).

# TypeScript
npm install ws

# Python
pip install "heisenberg_ai[stream]"

Subscribe

for await (const trade of hb.stream.trades({ condition_id: '0x…' })) {
    console.log(trade.price, trade.side, trade.proxy_wallet);
}

for trade in hb.stream.trades({"condition_id": "0x…"}):
    print(trade.get("price"), trade.get("side"), trade.get("proxy_wallet"))

Filters

Pass any combination; only trades matching all of them are delivered. Omit a filter to receive everything on that dimension.

Trade event fields

Reconnection & reliability

• On disconnect the client reconnects with exponential backoff and re-sends your subscription — the loop keeps yielding across drops.
• Control messages (subscription acks, rate-limit notices) are handled internally and not surfaced as trades.
• A fatal auth error ends the stream with an AuthError rather than reconnecting into a wall.
• Cap reconnects with maxReconnects (TS) / max_reconnects(Python) if you want it to give up after N attempts.

Stopping

const stream = hb.stream.trades({ slug: 'some-market' });
for await (const t of stream) {
    if (done(t)) break;   // breaking the loop closes the socket
}
// or pass an AbortSignal:  hb.stream.trades(filters, { signal })

for t in hb.stream.trades({"slug": "some-market"}):
    if done(t):
        break   # breaking closes the socket

The same stream is documented as a raw protocol under WebSockets if you want to connect without the SDK.