programSubscribe

POST

wss://sol.nownodes.io/wss/{api_key}

Subscribe to a program to receive notifications when the lamports or data for an account owned by the given program changes.

The optional dataSlice configuration limits the account data returned in each notification to a byte range. It does not change which accounts match the subscription or its filters.

Connection URL

Copied!

wss://sol.nownodes.io/wss/{api_key}

Open the WebSocket connection, then send one JSON-RPC request as a text frame.

Subscription request example

Copied!

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programSubscribe",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "encoding": "base64",
      "commitment": "confirmed",
      "dataSlice": {
        "offset": 0,
        "length": 32
      },
      "filters": [
        {
          "dataSize": 165
        }
      ]
    }
  ]
}

dataSlice.offset is the starting byte offset (zero-based), and dataSlice.length is the maximum number of bytes to return. In this example, each matching account notification contains the first 32 bytes of account data.

filters are evaluated against the account data as defined by the filter. In particular, dataSize refers to the full account data size, not the length of the returned dataSlice.

Use a binary account-data encoding such as base58 or base64 with dataSlice. The account space field, when present, describes the full account data size; it is not the length of the returned slice.

Subscription acknowledgement

After accepting the subscription, the server sends a JSON-RPC response containing the subscription ID:

Copied!

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

Notification format

Program account updates are sent in separate programNotification messages. Each notification contains one matching account object, as returned by getProgramAccounts; account.data contains only the requested slice when dataSlice is specified.

Base64 notification example (dataSlice: offset 0, length 32)

Copied!

{
  "jsonrpc": "2.0",
  "method": "programNotification",
  "params": {
    "result": {
      "context": {
        "slot": 5208469
      },
      "value": {
        "pubkey": "H4vnBqifaSACnKa7acsxstsY1iV1bvJNxsCY7enrd1hq",
        "account": {
          "data": [
            "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
            "base64"
          ],
          "executable": false,
          "lamports": 33594,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "rentEpoch": 636,
          "space": 165
        }
      }
    },
    "subscription": 24040
  }
}

The example's data value represents 32 returned bytes. The space value remains the full account data size.

Body

application/json

jsonrpcstring2.0required

JSON-RPC protocol version.

idinteger | stringrequired

Client request identifier.

methodstringprogramSubscriberequired

Solana WebSocket subscription method.

paramsArray<string | object>required

Positional parameters: program ID, then optional program subscription configuration.

Show child attributes

One of

Program ID whose accounts should be monitored.

string

encodingstringbase58base64base64+zstdjsonParsed

Account data encoding. Use base58 or base64 for sliced binary account data.

commitmentstringprocessedconfirmedfinalized

Commitment level for the subscription.

dataSliceobject

Return only a selected byte range of account data in each notification.

Show child attributes

offsetinteger>= 0required

Zero-based byte offset from which account data is returned.

lengthinteger>= 0required

Maximum number of bytes to return.

filtersArray<object | object>

Optional filters applied to matching accounts. Filters are evaluated against the full account data.

Show child attributes

One of

dataSizeinteger>= 0required

Match accounts whose full data size equals this value.

memcmpobjectrequired

Show child attributes

offsetinteger>= 0required

Byte offset at which to compare.

bytesstringrequired

Base58-encoded bytes to match.

encodingstringbase58base64

Encoding of the bytes value.

Parameters

api_keystringrequiredpath

Your NOWNodes API key.

Response

200OK

WebSocket subscription acknowledgement message. This is not a program update notification; updates arrive later as programNotification messages.

programSubscribe

curl -X POST 'wss://sol.nownodes.io/wss/{api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "programSubscribe",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "encoding": "base64",
        "commitment": "confirmed",
        "dataSlice": {
          "offset": 0,
          "length": 32
        },
        "filters": [
          {
            "dataSize": 165
          }
        ]
      }
    ]
  }'

import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider("wss://sol.nownodes.io/wss/{api_key}");
const result = await provider.send("programSubscribe", [
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  {
    "encoding": "base64",
    "commitment": "confirmed",
    "dataSlice": {
      "offset": 0,
      "length": 32
    },
    "filters": [
      {
        "dataSize": 165
      }
    ]
  }
]);
console.log(result);

require 'eth'
require 'json'
require 'net/http'

uri = URI('wss://sol.nownodes.io/wss/{api_key}')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request.body = '{
  "jsonrpc": "2.0",
  "method": "programSubscribe",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "encoding": "base64",
      "commitment": "confirmed",
      "dataSlice": {
        "offset": 0,
        "length": 32
      },
      "filters": [
        {
          "dataSize": 165
        }
      ]
    }
  ],
  "id": 1
}'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

from web3 import Web3

w3 = Web3(Web3.HTTPProvider("wss://sol.nownodes.io/wss/{api_key}"))
response = w3.provider.make_request("programSubscribe", [
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  {
    "encoding": "base64",
    "commitment": "confirmed",
    "dataSlice": {
      "offset": 0,
      "length": 32
    },
    "filters": [
      {
        "dataSize": 165
      }
    ]
  }
])
print(response)

import { createPublicClient, http } from "viem";

const client = createPublicClient({
  transport: http("wss://sol.nownodes.io/wss/{api_key}"),
});

const result = await client.request({
  method: "programSubscribe",
  params: [
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  {
    "encoding": "base64",
    "commitment": "confirmed",
    "dataSlice": {
      "offset": 0,
      "length": 32
    },
    "filters": [
      {
        "dataSize": 165
      }
    ]
  }
],
});

console.log(result);

const endpoint = "wss://sol.nownodes.io/wss/{api_key}";
const apiKey = "YOUR_API_KEY";

async function nownodesRequest(payload) {
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "api-key": apiKey,
    },
    body: JSON.stringify(payload),
  });

  return response.json();
}

const result = await nownodesRequest({ jsonrpc: "2.0", method: "programSubscribe", params: [
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  {
    "encoding": "base64",
    "commitment": "confirmed",
    "dataSlice": {
      "offset": 0,
      "length": 32
    },
    "filters": [
      {
        "dataSize": 165
      }
    ]
  }
], id: 1 });
console.log(result);

const response = await fetch('wss://sol.nownodes.io/wss/{api_key}', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "jsonrpc": "2.0",
      "id": 1,
      "method": "programSubscribe",
      "params": [
        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
        {
          "encoding": "base64",
          "commitment": "confirmed",
          "dataSlice": {
            "offset": 0,
            "length": 32
          },
          "filters": [
            {
              "dataSize": 165
            }
          ]
        }
      ]
    }),
});

const data = await response.json();

import requests

payload = {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programSubscribe",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "encoding": "base64",
      "commitment": "confirmed",
      "dataSlice": {
        "offset": 0,
        "length": 32
      },
      "filters": [
        {
          "dataSize": 165
        }
      ]
    }
  ]
}

response = requests.post('wss://sol.nownodes.io/wss/{api_key}', json=payload)
data = response.json()

require 'net/http'
require 'json'

uri = URI('wss://sol.nownodes.io/wss/{api_key}')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request.body = '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "programSubscribe",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "encoding": "base64",
        "commitment": "confirmed",
        "dataSlice": {
          "offset": 0,
          "length": 32
        },
        "filters": [
          {
            "dataSize": 165
          }
        ]
      }
    ]
  }'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
data = JSON.parse(response.body)

Request Body

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programSubscribe",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "encoding": "base64",
      "commitment": "confirmed",
      "dataSlice": {
        "offset": 0,
        "length": 32
      },
      "filters": [
        {
          "dataSize": 165
        }
      ]
    }
  ]
}

200

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