accountSubscribe

Subscribe to an account to receive notifications when the lamports or data for a given account public key changes

Common use cases

Wallet Balance Monitoring	Subscribe to a wallet's account to receive real-time lamport balance updates. Eliminates need for polling getAccountInfo, reducing API load while providing instant UI updates when funds are received or spent.
Token Account State Tracking	Monitor SPL token accounts with jsonParsed encoding for human-readable balance changes. Common in DEX interfaces, portfolio trackers, and payment systems that need immediate notification of token transfers.
NFT Ownership Verification	Track NFT metadata account updates to detect ownership changes, listing updates, or metadata modifications in real-time. Used by NFT marketplaces and wallet UIs to reflect current asset state.
DEX Pool Price Monitoring	Subscribe to AMM pool accounts to detect liquidity changes and price movements. Critical for arbitrage bots, price aggregators, and trading interfaces that require sub-second price updates.
Program Account State Synchronization	Monitor program-owned accounts for on-chain state changes (escrows, vaults, game state). Enables responsive dApps that react instantly to blockchain events rather than polling repeatedly.

Parameters

subscriptionId (string, required)

Account Pubkey, as base-58 encoded string

config (object, optional)

Configuration object containing the following fields:

Fields:

• commitment (string): The commitment describes how finalized a block is at that point in time. See Configuring State Commitment.
• encoding (string): Encoding format for Account data
  • base58 is slow.
  • jsonParsed encoding attempts to use program-specific state parsers to return more human-readable and explicit account state data
  • If jsonParsed is requested but a parser cannot be found, the field falls back to binary encoding, detectable when the data field is type string.

Request

wscat

wscat -c wss://solana-mainnet.api.syndica.io -x '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "accountSubscribe",
  "params": [
    "CM78CPUeXjn8o3yroDHxUtKsZZgoy4GPkPPXfouKNH12",
    {
      "encoding": "jsonParsed",
      "commitment": "finalized"
    }
  ]
}'

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": "accountSubscribe",
  "params": [
    "CM78CPUeXjn8o3yroDHxUtKsZZgoy4GPkPPXfouKNH12",
    {
      "encoding": "jsonParsed",
      "commitment": "finalized"
    }
  ]
}));
});

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": "accountSubscribe",
  "params": [
    "CM78CPUeXjn8o3yroDHxUtKsZZgoy4GPkPPXfouKNH12",
    {
      "encoding": "jsonParsed",
      "commitment": "finalized"
    }
  ]
}))
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": 23784,
  "id": 1
}

Response Fields

Return value: number

Subscription id (needed to unsubscribe)

Notification Format

The notification format is the same as seen in the getAccountInfo RPC HTTP method.

Base58 encoding:

{
  "jsonrpc": "2.0",
  "method": "accountNotification",
  "params": {
    "result": {
      "context": {
        "slot": 5199307
      },
      "value": {
        "data": [
          "11116bv5nS2h3y12kD1yUKeMZvGcKLSjQgX6BeV7u1FrjeJcKfsHPXHRDEHrBesJhZyqnnq9qJeUuF7WHxiuLuL5twc38w2TXNLxnDbjmuR",
          "base58"
        ],
        "executable": false,
        "lamports": 33594,
        "owner": "11111111111111111111111111111111",
        "rentEpoch": 635,
        "space": 80
      }
    },
    "subscription": 23784
  }
}

FAQ and Troubleshooting

What's the difference between accountSubscribe commitment levels?

processed provides fastest updates (200-400ms) but may be reverted during forks; confirmed offers reliability within ~1 second; finalized guarantees permanence after ~13 seconds. Use confirmed for UI updates and finalized for financial settlements.

How do I correlate subscription notifications to the original subscribe request?

The subscribe response contains "result": 23784 (subscription ID). All subsequent notifications include "subscription": 23784 to identify which account triggered the update. Store subscription IDs to map notifications back to UI components.

Which encoding should I use for account data?

Use jsonParsed for token accounts (readable balance/decimals), base64+zstd for compression on large accounts, base64 for standard accounts. Avoid base58 (deprecated and slow). dataSlice can reduce bandwidth by fetching only specific byte ranges.

Why did I get an "accountUnsubscribe error: socket not in right state" error?

You attempted to call accountSubscribe before the WebSocket reached OPEN state or after it closed. Always wait for the onopen event before subscribing, and only unsubscribe on active connections.

How many accountSubscribe subscriptions can I maintain simultaneously?

Most RPC providers limit to 100-1000 concurrent subscriptions per connection depending on tier. For monitoring many accounts, use getProgramAccounts for initial snapshot, then subscribe to ~10-50 critical accounts. Consider batching static data via HTTP methods.

Related Methods

accountUnsubscribe (WebSocket)
Cancels an active account subscription by subscription ID. Always call before closing WebSocket or when component unmounts to free server resources and prevent memory leaks. Returns true on success.

getAccountInfo
Fetches current account state via single HTTP request. Use for one-time reads or initial data load before establishing WebSocket subscription. accountSubscribe eliminates need for repeated polling.

programSubscribe (WebSocket)
Subscribe to all accounts owned by a program with optional filters. More efficient than multiple accountSubscribe calls when monitoring many program-owned accounts (e.g., all token accounts for a mint).

getMultipleAccounts
Batch-fetch multiple account states in single HTTP call. Common pattern: getMultipleAccounts for initial snapshot (100 accounts), then accountSubscribe to ~10-20 critical accounts for live updates.

signatureSubscribe (WebSocket)
Wait for transaction confirmation by signature. Complementary to accountSubscribe: use signatureSubscribe to confirm transaction landed, then accountSubscribe reflects resulting account state changes.

External Resources

• Solana Official Documentation
• Solana Cookbook: WebSocket Connections - Code examples for establishing WebSocket connections with Solana RPC nodes, including connection lifecycle management, error handling patterns, and subscription best practices. Shows TypeScript and Rust implementations.
• Anza agave: PubSub Client Source - Official Solana validator implementation of WebSocket subscription client. Demonstrates proper connection handling, subscription management, and automatic reconnection logic. Reference for building production-grade clients.