WebSocket Subscriptions

Subscribe to account changes, transaction logs, and signature confirmation over Solana WebSocket JSON-RPC.

Recipe

Quick-reference recipe card - copy-paste ready.

import { createSolanaRpcSubscriptions, address } from "@solana/kit";
 
const rpcSubscriptions = createSolanaRpcSubscriptions(
  "wss://api.devnet.solana.com"
);
 
const abort = new AbortController();
const accountNotifications = await rpcSubscriptions
  .accountNotifications(address("YOUR_ACCOUNT"), { commitment: "confirmed" })
  .subscribe({ abortSignal: abort.signal });
 
for await (const notification of accountNotifications) {
  console.log(notification.value.lamports);
}

When to reach for this:

• Live wallet balance updates without polling.
• Waiting for transaction confirmation in UI.
• Streaming program logs for a specific mention filter.
• Building reactive dashboards.

Working Example

import {
  createSolanaRpcSubscriptions,
  address,
} from "@solana/kit";
 
const rpcSubscriptions = createSolanaRpcSubscriptions(
  "wss://api.devnet.solana.com"
);
 
async function watchSignature(signature: string) {
  const abort = new AbortController();
  const sigNotifications = await rpcSubscriptions
    .signatureNotifications(signature, { commitment: "confirmed" })
    .subscribe({ abortSignal: abort.signal });
 
  for await (const n of sigNotifications) {
    if (n.value.err) {
      console.error("failed", n.value.err);
    } else {
      console.log("confirmed");
    }
    abort.abort();
    break;
  }
}
 
watchSignature("YOUR_TX_SIGNATURE");

What this demonstrates:

• signatureNotifications resolves when transaction reaches commitment.
• accountNotifications pushes new account state on writes.
• AbortController cleans up subscriptions on unmount.

Deep Dive

How It Works

• Client opens WebSocket, sends *Subscribe JSON-RPC method, receives push *Notification messages.
• Each subscription has an id for *Unsubscribe.
• Commitment on subscription controls notification timing.
• Provider WSS endpoints may require API key query params.

Subscription Types

TypeScript Notes

// Logs subscription with mentions filter (provider support varies)
// Use rpcSubscriptions.logsNotifications({ mentions: [programId] })

Gotchas

• HTTP URL on WebSocket client - connection fails. Fix: use wss:// endpoint from provider docs.
• Subscription leaks - open tabs accumulate server load. Fix: abort on component unmount and route change.
• processed notifications rollback - UI shows success then reverts. Fix: subscribe at confirmed or finalized.
• Public WSS rate limits - connections dropped under load. Fix: provider tier with higher subscription caps.
• Assuming ordering across accounts - notifications are per subscription. Fix: design idempotent UI merges.

Alternatives

FAQs

Related

• RPC Basics - HTTP vs WS
• Logs & Debugging - CLI log stream
• Webhooks - server-side events
• RPC Providers - WSS endpoints

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.