programSubscribe

The Solana programSubscribe method creates a subscription to receive real-time notifications whenever a lamports or data change occurs in any account owned by a specific program.

Usage Notes

• Must be called via a WebSocket endpoint; HTTP is not supported.
• If the WebSocket connection is dropped, subscriptions are automatically cancelled. You must re-subscribe upon reconnection.
• CU is consumed based on the volume of subscribed data, so it is recommended to use appropriate filtering options to subscribe only to the data you need.

---

1. Request

Parameters

The program subscription request accepts the following parameters.

Parameter	Type	Required	Description
id	integer or string	required	A unique identifier for the request. Used by the client to match requests with responses.
jsonrpc	string	required	The JSON-RPC protocol version. Always set to "2.0".
method	string	required	The name of the method to execute. Set to "programSubscribe" here.
params	array	required	Program information and options to subscribe to. The first element is the program ID, and the second is a configuration object.
params[0]	string	required	The Pubkey of the program to subscribe to (base-58 encoded string).
params[1].commitment	string	optional	Specifies the level of block commitment. - finalized: Queries the most recent block confirmed by a supermajority of the cluster at maximum lockout. The cluster recognizes this block as finalized. - confirmed: Queries the most recent block voted on by a supermajority of the cluster. - processed: Queries the node's most recent block. This block may still be skipped by the cluster.
params[1].filters	array	optional	An array of filter objects to filter results. Only accounts satisfying all filter conditions are included in the results.
params[1].encoding	string	optional	Encoding format for account data. - base58 (slow) - base64 - base64+zstd - jsonParsed (applies a parser if available, otherwise returns a binary string)

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programSubscribe",
  "params": [
    "11111111111111111111111111111111",
    {
      "encoding": "base64",
      "filters": [{ "dataSize": 80 }]
    }
  ]
}

---

2. Response

Subscription Response

Upon successful subscription creation, a subscription ID is returned.

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

This subscription ID is required when calling the programUnsubscribe method.

Notifications

Once the subscription is active, the server pushes notifications whenever the state of an account owned by the program changes. The notification format is identical to the getProgramAccounts RPC HTTP method.

Response data format:

• Response data is delivered in one of the following formats depending on the encoding option: base58, base64, base64+zstd, or jsonParsed.
• jsonParsed converts data to a human-readable format via program-specific parsers, but returns a binary string if no parser is available.

Base58 Encoding Example

{
  "jsonrpc": "2.0",
  "method": "programNotification",
  "params": {
    "result": {
      "context": {
        "slot": 5208469
      },
      "value": {
        "pubkey": "H4vnBqifaSACnKa7acsxstsY1iV1bvJNxsCY7enrd1hq",
        "account": {
          "data": [
            "11116bv5nS2h3y12kD1yUKeMZvGcKLSjQgX6BeV7u1FrjeJcKfsHPXHRDEHrBesJhZyqnnq9qJeUuF7WHxiuLuL5twc38w2TXNLxnDbjmuR",
            "base58"
          ],
          "executable": false,
          "lamports": 33594,
          "owner": "11111111111111111111111111111111",
          "rentEpoch": 636,
          "space": 80
        }
      }
    },
    "subscription": 24040
  }
}

JSON Parsed Encoding Example

{
  "jsonrpc": "2.0",
  "method": "programNotification",
  "params": {
    "result": {
      "context": {
        "slot": 5208469
      },
      "value": {
        "pubkey": "H4vnBqifaSACnKa7acsxstsY1iV1bvJNxsCY7enrd1hq",
        "account": {
          "data": {
            "program": "nonce",
            "parsed": {
              "type": "initialized",
              "info": {
                "authority": "Bbqg1M4YVVfbhEzwA9SpC9FhsaG83YMTYoR4a8oTDLX",
                "blockhash": "LUaQTmM7WbMRiATdMMHaRGakPtCkc2GHtH57STKXs6k",
                "feeCalculator": {
                  "lamportsPerSignature": 5000
                }
              }
            }
          },
          "executable": false,
          "lamports": 33594,
          "owner": "11111111111111111111111111111111",
          "rentEpoch": 636,
          "space": 80
        }
      }
    },
    "subscription": 24040
  }
}

---

3. How to Use

Connect to WebSocket Channel

wscat -c wss://api.mainnet-beta.solana.com

Subscribe to Program

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programSubscribe",
  "params": [
    "11111111111111111111111111111111",
    {
      "encoding": "base64",
      "filters": [{ "dataSize": 80 }]
    }
  ]
}

Receive Notifications

• Initial response: returns a subscription ID
• Subsequent: receive "programNotification" events when a change occurs in an account owned by the program

Unsubscribe

There are two ways to cancel a subscription:

1. Close the connection: Enter Ctrl+C in the terminal window to close the WebSocket connection, which automatically cancels all subscriptions.

2. Cancel a specific subscription: Use programUnsubscribe to cancel a specific subscription while keeping the connection open.

Unsubscribe request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "programUnsubscribe",
  "params": [24040]
}

Response after unsubscribe:

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