getTokenAccountsByOwnerV2 Solana RPC 方法

POST

getTokenAccountsByOwnerV2

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
    }
  ]
}
'

{
  "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"
  }
}

概述

getTokenAccountsByOwnerV2 是标准 getTokenAccountsByOwner 方法的增强版，专为高效查询代币投资组合和处理代币持有量庞大的钱包而设计。该方法引入了基于游标的分页和增量更新功能。

V2的新特性：

基于游标的分页：配置每个请求从1到10,000个token账户的限制
增量更新：使用changedSinceSlot仅获取最近修改的token账户
投资组合可扩展性：高效处理包含数千个token账户的钱包
向后兼容性：支持所有现有的getTokenAccountsByOwner参数和过滤器
可选的withContext：true在result.context下添加了slot和apiVersion；省略或false则不包含

过滤器要求：在查询中必须提供 mint （特定代币）或 programId （SPL代币或Token-2022程序）。不支持查询没有过滤器的所有代币类型。

主要优势

大型投资组合

处理具有数千个代币账户的钱包，不会出现超时或内存问题

实时跟踪

使用 changedSinceSlot 进行增量更新，实现投资组合的实时监控

`withContext`（可选）

配置对象（params[2]）上的布尔值。只有result的形状会改变，不包括过滤器、限制或分页。省略或false：result.value是token账户的数组。true：result.context加上result.value作为一个对象（accounts，paginationKey）。如果你处理两个，请分支到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 }
}}

分页最佳实践

重要的分页行为：只有在未返回任何token账户时才会指示分页结束。由于过滤的原因，API可能会返回少于你限制的账户——始终继续分页直到paginationKey是null。

基本投资组合查询

// 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}`);

增量投资组合更新

// 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程序支持

Token-2022支持：使用TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb作为programId来查询带有扩展功能的Token-2022账户，如转账费用、计息token等。

// 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 }
    ]
  })
});

从getTokenAccountsByOwner迁移

迁移很简单——只需将分页参数添加到你现有的查询中：

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

getTokenAccountsByOwner

无分页的原始方法

getProgramAccountsV2

用于程序账户查询的V2方法

请求参数

address

string

必填

要查询token持有的账户所有者的Solana钱包地址（pubkey），格式为base-58编码的字符串。

mint

string

特定 Solana 代币地址，仅检索特定代币或 NFT 的账户。

programId

string

创建代币账户的特定 Solana 代币程序 ID（通常是 SPL 代币程序）。

commitment

string

请求的承诺级别。

confirmed
finalized
processed

minContextSlot

number

请求可被评估的最小槽位。

withContext

boolean

当 true 时，返回 result.context（快照元数据：slot，apiVersion）并将 accounts 和 paginationKey 嵌套在 result.value 下作为对象。当 false 或省略时，result.value 是此页面的代币账户数组，paginationKey 在 result 上。应用相同的过滤器和限制。

dataSlice

object

请求账户数据的切片。

dataSlice.length

number

要返回的字节数。

dataSlice.offset

number

开始读取的字节偏移量。

encoding

string

账户数据的编码格式。

base58
base64
base64+zstd
jsonParsed

limit

number

每个请求返回的最大代币账户数量（1-10,000）。

paginationKey

string

用于获取后续页面的 Base-58 编码分页游标。使用之前响应中的 paginationKey。

changedSinceSlot

number

仅返回在此槽位号或之后修改的代币账户。对增量组合更新有用。

授权

api-key

string

query

必填

您的Helius API密钥。您可以在仪表板中免费获取一个。

请求体

application/json

jsonrpc

enum<string>

JSON-RPC 协议版本。

可用选项:

2.0

示例:

"2.0"

string

请求的唯一标识符。

示例:

"1"

method

enum<string>

默认值:getTokenAccountsByOwnerV2

要调用的 RPC 方法名称。

可用选项:

getTokenAccountsByOwnerV2

示例:

"getTokenAccountsByOwnerV2"

params

string · object · object[]

用于查询由特定公钥拥有的分页代币账户的参数。

要查询代币持有的账户所有者的 Solana 钱包地址（公钥），以 base-58 编码字符串表示。

示例:

"A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd"

响应

成功检索到按所有者分页的代币账户。

jsonrpc

enum<string>

JSON-RPC协议版本。

可用选项:

2.0

示例:

"2.0"

string

与请求匹配的标识符。

示例:

"1"

result

without withContext · object

当 withContext 为 false 或省略时的分页代币账户。匹配熟悉的形状，其中账户列表是一个数组的 result.value（不嵌套在 accounts 下）。

without withContext
with withContext

Show child attributes

getTokenLargestAccounts返回特定 SPL 代币类型的 20 个最大账户。

⌘I

getTokenAccountsByOwnerV2

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
    }
  ]
}
'

{
  "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"
  }
}

​概述

​主要优势

大型投资组合

实时跟踪

​withContext（可选）

​分页最佳实践

​基本投资组合查询

​增量投资组合更新

​Token程序支持

​从getTokenAccountsByOwner迁移

​相关方法

getTokenAccountsByOwner

getProgramAccountsV2

​请求参数

授权

请求体

响应

概述

主要优势

`withContext`（可选）

分页最佳实践

基本投资组合查询

增量投资组合更新

Token程序支持

从getTokenAccountsByOwner迁移

相关方法

请求参数