Skip to main content

Install

ws is an optional peer dependency. Install it only if you use the WebSocket client.

Building the client

Minimal:
Note that .build() is async - it establishes the WebSocket connection before resolving. If the connection fails, the promise rejects immediately.

Builder methods

.url(url) - Primary WebSocket endpoint. Falls back to ORBITFLARE_WS_URL env var.
.urls([...]) - Primary + fallbacks in one call.
.fallbackUrl(url) / .fallbackUrls([...]) - Add failover endpoints. On reconnect, the SDK rotates through them.
.apiKey(key) - License key. Falls back to ORBITFLARE_LICENSE_KEY env var.
.retry(policy) - Reconnection backoff. Default: 100ms initial, 30s max, 2x multiplier, infinite attempts.
.pingIntervalSecs(n) - How often the SDK sends WebSocket Ping frames. Default: 10.
.maxMissedPongs(n) - Pings without a response before killing the connection. Default: 3.

Available subscriptions

slotSubscribe()

Fires every time a slot is processed, confirmed, or finalized.
Each event is an object with slot, parent, and root fields:

accountSubscribe(address, commitment)

Fires when the specified account’s data changes.
Returns base64-encoded account data with lamports, owner, and executable flag.

logsSubscribe(mentions, commitment)

Fires for transactions that mention the given addresses. Pass an empty array for all transactions.
All logs:

signatureSubscribe(signature, commitment)

Fires once when a transaction reaches the given commitment level. Useful for confirming a transaction you just sent.

Reading events

All subscriptions return a WsSubscription. Call .next() to get the next event:
.next() resolves with undefined when the subscription is closed. You can also attach an event listener style callback:

Unsubscribing

This sends an unsubscribe message to the server. If you drop a subscription without calling this, the SDK detects the orphan and sends the unsubscribe automatically.

Multiple subscriptions

All subscriptions run on a single WebSocket connection. The SDK routes notifications to the right subscription internally.
You can add new subscriptions at any time while existing ones are running.

Reconnection

If the connection drops, the background task reconnects with exponential backoff and re-subscribes everything automatically. Your .next() calls just keep working - events resume once the connection is back.

Full example

A monitoring script that subscribes to slot updates and account changes for USDC, printing a live feed.