Skip to main content
POST
getTokenAccountsByOwnerV2

概述

getTokenAccountsByOwnerV2 是标准 getTokenAccountsByOwner 方法的增强版,专为高效查询代币投资组合和处理代币持有量庞大的钱包而设计。该方法引入了基于游标的分页和增量更新功能。
V2的新特性:
  • 基于游标的分页:配置每个请求从1到10,000个token账户的限制
  • 增量更新:使用changedSinceSlot仅获取最近修改的token账户
  • 投资组合可扩展性:高效处理包含数千个token账户的钱包
  • 向后兼容性:支持所有现有的getTokenAccountsByOwner参数和过滤器
  • 可选的withContexttrueresult.context下添加了slotapiVersion;省略或false则不包含
过滤器要求:在查询中必须提供 mint (特定代币)或 programId (SPL代币或Token-2022程序)。不支持查询没有过滤器的所有代币类型。

主要优势

大型投资组合

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

实时跟踪

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

withContext(可选)

配置对象(params[2])上的布尔值。只有result的形状会改变,不包括过滤器、限制或分页。省略或falseresult.value是token账户的数组trueresult.context加上result.value作为一个对象accountspaginationKey)。如果你处理两个,请分支到Array.isArray(result.value)

分页最佳实践

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

基本投资组合查询

增量投资组合更新

Token程序支持

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

从getTokenAccountsByOwner迁移

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

相关方法

getTokenAccountsByOwner

无分页的原始方法

getProgramAccountsV2

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

请求参数

string
必填
要查询token持有的账户所有者的Solana钱包地址(pubkey),格式为base-58编码的字符串。
string
特定 Solana 代币地址,仅检索特定代币或 NFT 的账户。
string
创建代币账户的特定 Solana 代币程序 ID(通常是 SPL 代币程序)。
string
请求的承诺级别。
  • confirmed
  • finalized
  • processed
number
请求可被评估的最小槽位。
boolean
true 时,返回 result.context(快照元数据:slotapiVersion)并将 accountspaginationKey 嵌套在 result.value 下作为对象。当 false 或省略时,result.value 是此页面的代币账户数组,paginationKeyresult 上。应用相同的过滤器和限制。
object
请求账户数据的切片。
number
要返回的字节数。
number
开始读取的字节偏移量。
string
账户数据的编码格式。
  • base58
  • base64
  • base64+zstd
  • jsonParsed
number
每个请求返回的最大代币账户数量(1-10,000)。
string
用于获取后续页面的 Base-58 编码分页游标。使用之前响应中的 paginationKey。
number
仅返回在此槽位号或之后修改的代币账户。对增量组合更新有用。

授权

api-key
string
query
必填

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

请求体

application/json
jsonrpc
enum<string>
默认值:2.0

JSON-RPC 协议版本。

可用选项:
2.0
示例:

"2.0"

id
string
默认值:1

请求的唯一标识符。

示例:

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

id
string

与请求匹配的标识符。

示例:

"1"

result
without withContext · object

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