Streams (SSE)

Real-time data via Server-Sent Events. Long-lived HTTP connections — prices and pool discoveries push to your client as they happen.

Requires API key. SSE streams bypass the cache (long-lived connections).

GET /v1/stream/prices?tokens=SOL,BTC,ETH

Stream real-time price updates. Fires on every pool state change for subscribed tokens.

Query parameters:

• tokens — Comma-separated token symbols (required)

Headers:

X-API-Key: your_api_key

Event format:

event: price
data: {"token":"SOL","priceUsd":80.31,"bestBid":80.07,"bestAsk":80.54,"bestBidPool":"BmXV...","bestAskPool":"Ahho...","bestBidDex":"orca-whirlpool","bestAskDex":"orca-whirlpool","bestBidFeeBps":1,"bestAskFeeBps":1,"poolCacheAgeMs":150,"poolCount":31,"timestamp":1712000000000,"route":"direct"}

event: heartbeat
data: {"ts":1712000015000}

Events:

Event	Description	Frequency
price	Token price updated (pool state changed)	Per pool update (~1-10/sec for active tokens)
heartbeat	Connection keepalive	Every 15 seconds

Deduplication: Consecutive price updates with <0.01% change in priceUsd are suppressed to reduce noise.

Initial data: On connect, the current price for each subscribed token is sent immediately.

Example (JavaScript):

const es = new EventSource(
  'https://api.venum.dev/v1/stream/prices?tokens=SOL,BTC,ETH',
  { headers: { 'X-API-Key': 'your_key' } }
);

es.addEventListener('price', (e) => {
  const price = JSON.parse(e.data);
  console.log(`${price.token}: $${price.priceUsd}`);
});

Example (curl):

curl -N -H "X-API-Key: your_key" \
  "https://api.venum.dev/v1/stream/prices?tokens=SOL,BTC"

GET /v1/stream/pools

Stream new pool discoveries in real-time.

Headers:

X-API-Key: your_api_key

Event format:

event: new-pool
data: {"address":"HJPj...","dex":"raydium-cpmm","mintA":"So111...","mintB":"EPjF...","discoveredAt":1712000000000}

event: heartbeat
data: {"ts":1712000015000}

Events:

Event	Description
new-pool	New liquidity pool detected on-chain
heartbeat	Connection keepalive (every 15s)

GET /v1/stream/tx?signatures=sig1,sig2

Optimistic transaction confirmation via ShredStream. Pushes when a submitted transaction is seen in a block shred — typically ~200ms after landing, before RPC confirmation.

Query parameters:

• signatures — Comma-separated base58 transaction signatures (1-10, required)

Headers:

X-API-Key: your_api_key

Event format:

event: tx
data: {"signature":"2rFf8q...","status":"landed","slot":411007599}

event: tx
data: {"signature":"2rFf8q...","status":"timeout"}

Events:

Event	Description
tx	Transaction status update

Status values:

Status	Meaning
landed	Transaction seen in a block shred (optimistic, pre-confirmation)
timeout	Not seen within 15 seconds

Behavior:

• Stream closes automatically when all signatures are resolved (landed or timeout).
• Open the SSE connection before submitting the transaction to avoid missing fast confirmations.
• For resilience, fall back to polling GET /v1/tx/:signature if SSE fails to connect.

Example (curl):

curl -N -H "X-API-Key: your_key" \
  "https://api.venum.dev/v1/stream/tx?signatures=2rFf8qgx..."

Connection Handling

• Auto-reconnect: Streams end on server restart. Clients should reconnect automatically (built into EventSource API).
• Timeout: Connections stay open up to 1 hour. Reconnect after.
• Heartbeat: If no heartbeat received in 30 seconds, the connection is likely dead — reconnect.
• Backpressure: If your client can't keep up, events may be dropped. Process events asynchronously.