programUnsubscribe

Unsubscribe from program-owned account change notifications

Common use cases

Component lifecycle cleanup	Call programUnsubscribe in React useEffect cleanup or Vue onUnmounted hooks to prevent memory leaks when components unmount. Essential for single-page applications where program monitoring components mount and unmount dynamically. Ensures server resources freed and prevents stale event handlers from firing after component destruction.
Switching between programs	Unsubscribe from current program subscription before subscribing to another when user changes monitoring target (e.g., switching between token programs or DeFi protocols in a dashboard). Prevents accumulation of obsolete subscriptions and reduces unnecessary server-to-client bandwidth. Returns true on successful cleanup.
Graceful shutdown and reconnection	Cancel all active program subscriptions before closing WebSocket connection or during reconnection logic. While server auto-cleans up on disconnect, explicit unsubscribe ensures immediate resource release, prevents race conditions, and enables deterministic cleanup in connection pools or retry scenarios.

Parameters

subscriptionId (number, required)

id of account Subscription to cancel

Request

wscat

wscat -c wss://solana-mainnet.api.syndica.io -x '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programUnsubscribe",
  "params": [
    0
  ]
}'

JavaScript

const ws = new WebSocket('wss://solana-mainnet.api.syndica.io');

ws.on('open', function open() {
  ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programUnsubscribe",
  "params": [
    0
  ]
}));
});

ws.on('message', function incoming(data) {
  console.log(data);
});

Python

import websocket
import json

ws = websocket.create_connection('wss://solana-mainnet.api.syndica.io')
ws.send(json.dumps({
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programUnsubscribe",
  "params": [
    0
  ]
}))
result = ws.recv()
print(result)
ws.close()

Network Selection

Replace mainnet with devnet in the URL to query devnet instead.

Response

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 1
}

Response Fields

Return value: boolean

unsubscribe success message

FAQ and Troubleshooting

What happens if I call programUnsubscribe with an invalid subscription ID?

Returns JSON-RPC error with code -32602 and message "Invalid subscription id." This occurs when subscription ID doesn't exist, was already unsubscribed, or connection lost subscription state. Always store subscription IDs from programSubscribe responses and handle errors gracefully.

Do I need to unsubscribe before closing the WebSocket connection?

While WebSocket closure automatically cleans up subscriptions server-side, explicit programUnsubscribe is best practice. It immediately frees resources, prevents race conditions, and ensures deterministic cleanup, especially for connection pools or reconnection scenarios where connection state may be uncertain.

Can I unsubscribe from a subscription created on a different WebSocket connection?

No. Subscription IDs are scoped to the WebSocket connection that created them. Each connection maintains its own subscription namespace. Attempting to unsubscribe a subscription ID from a different connection returns "Invalid subscription id" error.

Can I reuse a subscription ID after calling programUnsubscribe?

No, subscription IDs are single-use only. After unsubscribing, you must call programSubscribe again to get a new subscription ID. Attempting to use an old subscription ID will return "Invalid subscription id" error.

When should I call programUnsubscribe?

Always unsubscribe when you stop needing program account updates—on application shutdown, component unmount, route changes, or when switching monitoring targets. This prevents resource leaks on both client and server, reduces bandwidth waste, and ensures clean subscription lifecycle management.

Related Methods

programSubscribe
Creates the program account subscription that programUnsubscribe cancels. Returns subscription ID required for unsubscribe. Every programSubscribe should have corresponding programUnsubscribe for proper resource management and cleanup.

accountUnsubscribe
Similar cleanup pattern for single account subscriptions. Same parameter (subscription ID) and return type (boolean). Use same cleanup practices as programUnsubscribe—call in component unmount, route change, or shutdown handlers.

logsUnsubscribe
Cancel logsSubscribe for transaction log monitoring. Follows identical unsubscribe pattern with subscription ID parameter. Part of standard WebSocket subscription cleanup workflow alongside programUnsubscribe.

slotUnsubscribe
Cleanup slot subscriptions using same unsubscribe pattern. Single subscription ID parameter, returns boolean. All *Unsubscribe methods follow this consistent interface for predictable cleanup behavior.

getProgramAccounts
HTTP method to fetch program accounts snapshot without subscription. Use for one-time queries where programSubscribe + programUnsubscribe lifecycle overhead is unnecessary. No cleanup required since HTTP requests are stateless.

External Resources

• Solana Official Documentation
• Anza agave: RPC PubSub Implementation - Official validator source code showing server-side unsubscribe logic and subscription cleanup. Includes test coverage demonstrating proper error handling for invalid subscription IDs and subscription lifecycle management.
• Solana WebSocket API - Official RPC WebSocket documentation covering subscription lifecycle and cleanup patterns. Provides context for when to use programUnsubscribe alongside other WebSocket subscription methods.