WebSocket Subscriptions

When you need to react the instant an account changes or a transaction settles, polling JSON-RPC in a loop is wasteful: most calls return nothing new, you burn compute units, and you still lag the chain. Solana's WebSocket PubSub interface inverts that — you open one persistent connection to wss://solana.therpc.io/YOUR_API_KEY, register interest once, and the server pushes a notification the moment something matches. Given ~400ms slots, that push model is the only way to feel truly live without hammering the endpoint. This guide covers the main *Subscribe methods and the full notification lifecycle, from the subscription id you get back to the *Unsubscribe call that cleans the stream up.

Understanding PubSub

• One wss endpoint. All PubSub runs over wss://solana.therpc.io/YOUR_API_KEY — the same API key as your HTTP endpoint, used in the WebSocket URL path.
• Subscribe, then receive. A *Subscribe call returns a numeric subscription id. The server then streams *Notification messages that each carry that id, so you can route a notification to the right handler when several subscriptions share one socket.
• The main subscriptions. accountSubscribe (one account), programSubscribe (every account a program owns), logsSubscribe (transaction logs), signatureSubscribe (one transaction's outcome), and slotSubscribe (each new slot).
• signatureSubscribe is one-shot. It fires a single notification when the signature reaches your chosen commitment and then auto-cancels — ideal for confirming a send without a polling loop.
• Unsubscribe to free resources. Streams do not stop on their own. Call the matching *Unsubscribe with the subscription id to end a stream and release the server-side resources it holds.
• Filter the firehoses. programSubscribe and logsSubscribe can match enormous volume. Always narrow them with filters (a memcmp/dataSize filter, or mentions for logs) so the socket is not flooded with traffic you do not need.

Subscribing to an Account

1import { Connection, PublicKey } from '@solana/web3.js';
2 
3// The library opens the wss endpoint for you when you subscribe
4const connection = new Connection('https://solana.therpc.io/YOUR_API_KEY', {
5  commitment: 'confirmed',
6  wsEndpoint: 'wss://solana.therpc.io/YOUR_API_KEY',
7});
8 
9const pubkey = new PublicKey('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM');
10 
11// Push notifications when the account changes
12const subId = connection.onAccountChange(
13  pubkey,
14  (accountInfo, context) => {
15    console.log('Slot', context.slot, 'new lamports:', accountInfo.lamports);
16  },
17  'confirmed',
18);
19 
20// Later: stop the stream
21// await connection.removeAccountChangeListener(subId);

Raw PubSub Frames

// Request over the wss connection
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "accountSubscribe",
  "params": [
    "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    { "encoding": "jsonParsed", "commitment": "confirmed" }
  ]
}
 
// Server pushes notifications carrying the subscription id
{
  "jsonrpc": "2.0",
  "method": "accountNotification",
  "params": {
    "subscription": 23784,
    "result": {
      "context": { "slot": 250000000 },
      "value": { "lamports": 1000000000, "owner": "11111111111111111111111111111111" }
    }
  }
}

Best Practices

• Filter before you subscribe. Scope programSubscribe with a memcmp/dataSize filter and logsSubscribe with mentions, so the server only pushes the accounts and logs you actually care about instead of flooding the socket.
• Track ids and unsubscribe. Store every subscription id and call the matching *Unsubscribe when a component or view unmounts. Forgotten subscriptions leak both client memory and server-side resources.
• Reconnect with backoff. WebSockets drop. On disconnect, reconnect with exponential backoff and re-issue every *Subscribe — the server does not restore subscriptions for you.
• Keep the socket alive. Send a periodic ping (roughly every 60 seconds) and watch for the pong so idle connections are not silently closed by intermediaries.
• Confirm with signatureSubscribe. For transaction confirmation, prefer the one-shot signatureSubscribe over a tight getSignatureStatuses polling loop — it delivers the result the instant the signature reaches your commitment and cancels itself.

See also

• accountSubscribe - Notify on account changes
• logsSubscribe - Notify on transaction logs
• signatureSubscribe - Notify once when a signature settles
• slotSubscribe - Notify on each new slot