getProgramAccountsV2

Enhanced version of getProgramAccounts with cursor-based pagination and changedSinceSlot support for efficiently querying large sets of accounts owned by specific Solana programs with incremental updates.

POST

getProgramAccountsV2

cURL

curl --request POST \
  --url 'https://mainnet.helius-rpc.com/?api-key=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getProgramAccountsV2",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "encoding": "base64",
      "limit": 1000
    }
  ]
}
'

200

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "accounts": [
      {
        "pubkey": "CxELquR1gPP8wHe33gZ4QxqGB3sZ9RSwsJ2KshVewkFY",
        "account": {
          "lamports": 15298080,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "data": [
            "2R9jLfiAQ9bgdcw6h8s44439",
            "base64"
          ],
          "executable": false,
          "rentEpoch": 28,
          "space": 165
        }
      }
    ],
    "paginationKey": "8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
  }
}

Overview

getProgramAccountsV2 is an enhanced version of the standard getProgramAccounts method, designed for applications that need to efficiently query large sets of accounts owned by specific Solana programs. This method introduces cursor-based pagination and incremental update capabilities.

New Features in V2:

• Cursor-based pagination: Configure limits from 1 to 10,000 accounts per request
• Incremental updates: Use changedSinceSlot to fetch only recently modified accounts
• Better performance: Prevents timeouts and reduces memory usage for large datasets
• Backward compatibility: Supports all existing getProgramAccounts parameters
• Optional withContext: true adds slot and apiVersion under result.context; omit or false and they are not included

Key Benefits

Scalable Queries

Handle programs with millions of accounts by paginating through results efficiently

Real-time Sync

Use changedSinceSlot for incremental updates and real-time data synchronization

Prevent Timeouts

Large queries that previously timed out now work reliably with pagination

Memory Efficient

Process data in chunks instead of loading everything into memory at once

Pagination Best Practices

Important Pagination Behavior: End of pagination is only indicated when no accounts are returned. The API may return fewer accounts than your limit due to filtering - always continue pagination until paginationKey is null.

Basic Pagination Pattern

let allAccounts = [];
let paginationKey = null;

do {
  const response = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: '1',
      method: 'getProgramAccountsV2',
      params: [
        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
        {
          encoding: 'base64',
          filters: [{ dataSize: 165 }],
          limit: 5000,
          ...(paginationKey && { paginationKey })
        }
      ]
    })
  });
  
  const data = await response.json();
  allAccounts.push(...data.result.accounts);
  paginationKey = data.result.paginationKey;
} while (paginationKey);

Incremental Updates

// Get only accounts modified since slot 150000000
const incrementalUpdate = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getProgramAccountsV2',
    params: [
      programId,
      {
        encoding: 'jsonParsed',
        limit: 1000,
        changedSinceSlot: 150000000
      }
    ]
  })
});

Performance Tips

Optimal Limit Size: For most use cases, a limit of 1,000-5,000 accounts per request provides the best balance of performance and reliability.

• Start with smaller limits (1000) and increase based on your network performance
• Use appropriate encoding: jsonParsed for convenience, base64 for performance
• Apply filters to reduce the dataset size before pagination
• Store paginationKey to resume queries if interrupted
• Monitor response times and adjust limits accordingly

withContext (optional)

Boolean on the program config object (params[1]). Only the shape of result changes, not filters, limits, or pagination.

// Omitted or false
{ "jsonrpc": "2.0", "id": "1", "result": { "accounts": [], "paginationKey": null } }

// true — snapshot metadata plus page under `result.value`
{ "jsonrpc": "2.0", "id": "1", "result": {
  "context": { "slot": 411895550, "apiVersion": "3.1.9" },
  "value": { "accounts": [], "paginationKey": null }
}}

Migration from getProgramAccounts

Migrating from the original method is straightforward - simply replace the method name and add pagination parameters:

{
  "jsonrpc": "2.0",
  "id": "1",
- "method": "getProgramAccounts",
+ "method": "getProgramAccountsV2",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "encoding": "base64",
      "filters": [{ "dataSize": 165 }],
+     "limit": 5000
    }
  ]
}

Related Methods

getProgramAccounts

Original method without pagination

getTokenAccountsByOwnerV2

V2 method for token account queries

Request Parameters

address · string · required

The Solana program public key (address) to query accounts for, as a base-58 encoded string.

commitment · string

The commitment level for the request.

• confirmed
• finalized
• processed

minContextSlot · number

The minimum slot that the request can be evaluated at.

withContext · boolean

When true, returns result.context (snapshot metadata: slot, apiVersion) and nests accounts and paginationKey under result.value. When false or omitted, those fields appear directly on result (for example result.accounts). Same filters and limits apply.

encoding · string

Encoding format for the returned account data.

• jsonParsed
• base58
• base64
• base64+zstd

dataSlice · object

Request a slice of the account’s data.

dataSlice.length · number

Number of bytes to return.

dataSlice.offset · number

Byte offset from which to start reading.

limit · number

Maximum number of accounts to return per request (1-10,000).

paginationKey · string

Base-58 encoded pagination cursor for fetching subsequent pages. Use the paginationKey from previous response.

changedSinceSlot · number

Only return accounts that were modified at or after this slot number. Useful for incremental updates.

filters · array

Powerful filtering system to efficiently query specific Solana account data patterns.

Authorizations

api-key · string · query · required

Your Helius API key. You can get one for free in the dashboard.

Body

application/json

jsonrpc · enum<string> · default: 2.0 · required

The JSON-RPC protocol version.

Available options: 2.0

Example:

"2.0"

id · string · default: 1 · required

A unique identifier for the request.

Example:

"1"

method · enum<string> · default: getProgramAccountsV2 · required

The name of the RPC method to invoke.

Available options: getProgramAccountsV2

Example:

"getProgramAccountsV2"

params · (string | object)[] · required

Parameters for the enhanced paginated method.

The Solana program public key (address) to query accounts for, as a base-58 encoded string.

Example:

"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"

Response

200

application/json

Successfully retrieved paginated program accounts.

jsonrpc · enum<string>

The JSON-RPC protocol version.

Available options: 2.0

Example:

"2.0"

id · string

Identifier matching the request.

Example:

"1"

result · without withContext · object

Paginated program accounts. Same fields appear on result when withContext is false or omitted, or under result.value when withContext is true.

without withContext

with withContext

Show child attributes