getTokenAccountsByOwnerV2

Enhanced version of getTokenAccountsByOwner with additional features including cursor-based pagination and changedSinceSlot support for efficiently retrieving SPL token accounts owned by a specific wallet address.

POST

getTokenAccountsByOwnerV2

cURL

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

200

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "value": [
      {
        "pubkey": "BGocb4GEpbTFm8UFV2VsDSaBXHELPfAXrvd4vtt8QWrA",
        "account": {
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "isNative": false,
                "mint": "2cHr7QS3xfuSV8wdxo3ztuF4xbiarF6Nrgx3qpx3HzXR",
                "owner": "A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "420000000000000",
                  "decimals": 6,
                  "uiAmount": 420000000,
                  "uiAmountString": "420000000"
                }
              }
            },
            "space": 165
          },
          "executable": false,
          "rentEpoch": 18446744073709552000,
          "space": 165
        }
      }
    ],
    "paginationKey": "8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
  }
}

Overview

getTokenAccountsByOwnerV2 is an enhanced version of the standard getTokenAccountsByOwner method, specifically designed for efficiently querying token portfolios and handling wallets with extensive token holdings. This method introduces cursor-based pagination and incremental update capabilities.

New Features in V2:

• Cursor-based pagination: Configure limits from 1 to 10,000 token accounts per request
• Incremental updates: Use changedSinceSlot to fetch only recently modified token accounts
• Portfolio scalability: Handle wallets with thousands of token accounts efficiently
• Backward compatibility: Supports all existing getTokenAccountsByOwner parameters and filters
• Optional withContext: true adds slot and apiVersion under result.context; omit or false and they are not included

Filter Requirement: You must provide either a mint (specific token) or programId (SPL Token or Token-2022 program) in your query. Querying all token types for an owner without a filter is not supported.

Key Benefits

Large Portfolios

Handle wallets with thousands of token accounts without timeouts or memory issues

Real-time Tracking

Monitor portfolio changes in real-time using changedSinceSlot for incremental updates

withContext (optional)

Boolean on the config object (params[2]). Only the shape of result changes, not filters, limits, or pagination. Omitted or false: result.value is the token account array. true: result.context plus result.value as an object (accounts, paginationKey). If you handle both, branch on Array.isArray(result.value).

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

// true
{ "jsonrpc": "2.0", "id": "1", "result": {
  "context": { "slot": 411895550, "apiVersion": "3.1.9" },
  "value": { "accounts": [], "paginationKey": null }
}}

Pagination Best Practices

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

Basic Portfolio Query

// Get all SPL Token accounts for a wallet
let allTokenAccounts = [];
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: 'getTokenAccountsByOwnerV2',
      params: [
        "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", // wallet address
        { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
        {
          encoding: 'jsonParsed',
          limit: 1000,
          ...(paginationKey && { paginationKey })
        }
      ]
    })
  });
  
  const data = await response.json();
  allTokenAccounts.push(...data.result.value);
  paginationKey = data.result.paginationKey;
} while (paginationKey);

console.log(`Total token accounts: ${allTokenAccounts.length}`);

Incremental Portfolio Updates

// Get only token accounts modified since a specific slot
const portfolioUpdates = 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: 'getTokenAccountsByOwnerV2',
    params: [
      walletAddress,
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      {
        encoding: 'jsonParsed',
        limit: 1000,
        changedSinceSlot: lastUpdateSlot // Only get recent changes
      }
    ]
  })
});

Token Program Support

Token-2022 Support: Use TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb as the programId to query Token-2022 accounts with extensions like transfer fees, interest-bearing tokens, and more.

// Query Token-2022 accounts (supports token extensions)
const token2022Response = 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: 'getTokenAccountsByOwnerV2',
    params: [
      walletAddress,
      { "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" }, // Token-2022
      { encoding: 'jsonParsed', limit: 1000 }
    ]
  })
});

Migration from getTokenAccountsByOwner

Migration is simple - just add pagination parameters to your existing queries:

{
  "jsonrpc": "2.0",
  "id": "1",
- "method": "getTokenAccountsByOwner",
+ "method": "getTokenAccountsByOwnerV2",
  "params": [
    "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
    {
      "encoding": "jsonParsed",
+     "limit": 1000
    }
  ]
}

Related Methods

getTokenAccountsByOwner

Original method without pagination

getProgramAccountsV2

V2 method for program account queries

Request Parameters

address · string · required

Solana wallet address (pubkey) of the account owner to query token holdings for, as a base-58 encoded string.

mint · string

Specific Solana token mint address to retrieve only accounts for a particular token or NFT.

programId · string

Specific Solana token program ID (typically SPL Token program) that created the token accounts.

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 as an object. When false or omitted, result.value is the token account array for this page, with paginationKey on result. Same filters and limits apply.

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.

encoding · string

Encoding format for Account data.

• base58
• base64
• base64+zstd
• jsonParsed

limit · number

Maximum number of token 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 token accounts that were modified at or after this slot number. Useful for incremental portfolio updates.

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>

The JSON-RPC protocol version.

Available options: 2.0

Example:

"2.0"

id · string

A unique identifier for the request.

Example:

"1"

method · enum<string> · default: getTokenAccountsByOwnerV2

The name of the RPC method to invoke.

Available options: getTokenAccountsByOwnerV2

Example:

"getTokenAccountsByOwnerV2"

params · string · object · object[]

Parameters for querying paginated token accounts owned by a specific public key.

Solana wallet address (pubkey) of the account owner to query token holdings for, as a base-58 encoded string.

Example:

"A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd"

Response

200

application/json

Successfully retrieved paginated token accounts by owner.

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 token accounts when withContext is false or omitted. Matches the familiar shape where the account list is result.value as an array (not nested under accounts).

without withContext

with withContext

Show child attributes