GET /v1/stream/accounts

Stream real-time updates for accounts owned by a Solana program, filtered server-side by dataSize and optional memcmp byte matches. Matches the filter primitives you already use with getProgramAccounts, delivered over SSE so the work the client used to poll for now arrives push-style.

Request

GET /v1/stream/accounts?programId=whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc&dataSize=653
x-api-key: YOUR_API_KEY

Browser-native EventSource cannot set custom headers. For browser clients, use ?apiKey=YOUR_API_KEY instead.

Query parameters

Field	Type	Required	Default	Description
programId	string	Yes	—	Base58-encoded 32-byte program pubkey to watch
dataSize	integer	No	(any)	Exact account data length to match
memcmp	string	No	(none)	Repeatable: offset:base58Bytes. Up to 4 entries, ≤ 64 bytes each
includeOptimistic	boolean	No	false	Also receive pre-confirmation predicted updates

Multiple memcmp filters can be combined with dataSize. All filters must match for an update to be delivered to your stream.

Events

Event	Description
ready	Stream accepted; sent immediately on connect
account	Confirmed account update at the slot indicated
account-optimistic	Pre-confirmation predicted update (only when includeOptimistic=true)
heartbeat	Connection keepalive
error	Terminal error; the server closes the stream after this event

Example payload

event: account
data: {"address":"BqnpCdDLPV2pXuPLghYJgRopSnyqWzVxQpcKgwsCe9w","owner":"whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc","slot":284502931,"lamports":null,"data":"AQAAAA...base64...","confidence":"confirmed"}

The data field is a base64-encoded copy of the raw on-chain account bytes — the same shape getProgramAccounts would have returned for that account at that slot. Decode it with your program's existing schema.

Confidence model

confidence	Meaning
optimistic	Pre-confirmation predicted state, usually the lowest-latency update
confirmed	Observed at processed commitment from on-chain state

Optimistic events are followed by the matching confirmed event at the same slot. Consumers that need strict consistency should ignore optimistic (do not set includeOptimistic=true) or reconcile by (address, slot) and act only on confidence: "confirmed".

Slot ordering is preserved within a single subscription. Within a slot, a single account may produce one or two events (an optimistic emit and a confirmed emit). Treat the latest event for a given address as authoritative.

Initial snapshot

On connect, the server emits one account event per currently-known matching account before live updates begin. Subscribers then receive updates as they happen. There is no replay buffer beyond the connect-time snapshot — reconnect to receive a fresh snapshot.

Example

curl -N -H "x-api-key: YOUR_API_KEY" \
  "https://api.venum.dev/v1/stream/accounts?programId=whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc&dataSize=653"

# Browser/EventSource fallback
curl -N \
  "https://api.venum.dev/v1/stream/accounts?programId=whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc&dataSize=653&apiKey=YOUR_API_KEY"

Filter by memcmp (token account vault authority):

curl -N -H "x-api-key: YOUR_API_KEY" \
  "https://api.venum.dev/v1/stream/accounts?\
programId=TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA&\
dataSize=165&\
memcmp=32:5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1"

Errors

Status	Body	Description
400	programId required	programId query param missing
400	programId must be a base58 32-byte pubkey	Bad programId encoding
400	dataSize must be a non-negative integer	Bad dataSize value
400	malformed memcmp filter: …	Bad memcmp shape (expect offset:base58Bytes)
400	memcmp bytes length out of range: …	memcmp bytes empty or > 64 bytes
400	too many memcmp filters (max 4)	Too many memcmp entries
401	Invalid or missing API key	Auth required
429	SSE connection limit exceeded	Exceeded your plan's concurrent SSE connection cap
503	service-disabled	Endpoint temporarily disabled by the operator

Latency

Best-effort sub-second on common programs. No latency guarantee. If you need hard sub-second guarantees across all programs, run your own validator with a Geyser plugin.

Rate Limit

Counts against the SSE streams connection limit in Plans & Rate Limits.