跳转到主要内容
POST
getHistoricalTokenAccountsByOwner
getHistoricalTokenAccountsByOwner 目前处于 Beta 阶段。参数、定价、响应格式和数据覆盖范围可能会发生变化。

概述

getHistoricalTokenAccountsByOwner 返回钱包在过去某个时隙拥有的 SPL Token 和 Token-2022 账户,或该时隙中特定交易执行后立即呈现的账户。这是 Helius 独有的 RPC 方法。标准 getTokenAccountsByOwner 仅返回当前状态。 使用 jsonParsed 编码时,代币数量会采用每个铸币在请求位置时的小数位数,因此余额反映钱包在该时间点持有的数量。 历史数据从时隙 444,959,999(2026 年 9 月 7 日)开始提供,该时隙对应纪元 1030 开始时的状态。 getHistoricalTokenAccountsByOwner 可在主网的 Business 及更高级别套餐中使用,Beta 期间每次调用消耗 0 个额度。定价可能会发生变化。

与 getTokenAccountsByOwner 的区别

  • 铸币或程序筛选条件为可选项。 不设置筛选条件时,你会获得钱包拥有的所有代币账户。若要缩小结果范围,请在配置对象(第三个参数)中设置 mint 或 programId,但不能同时设置两者。
  • 第二个参数是查询对象,用于选择历史记录中的位置,而不是铸币或程序筛选条件。
  • result.value 是一个对象,包含 accounts 和 paginationKey,而不是数组。

选择历史记录中的位置

第二个参数是查询对象:
  • 省略或设为 {}:最新的已索引时隙,但不超过所请求确认级别允许的范围。
  • { "slot": 445000000 }:时隙 445,000,000 结束时。
  • { "slot": 445000000, "transactionIndex": 10 }:该时隙中索引为 10 的交易执行后立即呈现的状态。
有关位置的工作原理,请参阅历史账户指南。

请求示例

此请求返回钱包在时隙 445,000,000 结束时的 USDC 代币账户:

分页获取所有代币账户

结果先按铸币排序,再按代币账户地址排序。每个响应都会返回 value.accounts 和 value.paginationKey,后者是格式为 <mint>:<tokenAccount> 的游标。将其传入下一个请求,直到它变为 null。
即使某一页的结果很少甚至为空,也可能仍包含 paginationKey。只有当 paginationKey 为 null 时,才表示已到达末尾。
分页时,请始终显式传入 slot。如果省略,每一页都会读取最新的已索引时隙,因此不同页面的数据可能来自不同时间点。

读取响应

value.accounts 中的每个条目都包含代币账户的 pubkey 和一个 account 对象。该账户对象包含与 getAccountInfo 相同的字段,并额外包含 lastUpdatedAt:
  • lastUpdatedAt.slot 和 lastUpdatedAt.transactionIndex 标识生成此状态的写入操作。
  • lastUpdatedAt.slot 为 444,959,999 且 transactionIndex 为 null,表示自历史数据覆盖开始以来,该代币账户一直没有变化。
  • context.slot 是 Helius 处理请求时已索引的最新时隙,而不是你查询的时隙。

错误

相关方法

Historical Accounts Guide

了解历史账户方法中的位置、数据覆盖范围和 lastUpdatedAt 的工作原理

getHistoricalAccountInfo

读取单个账户在过去某个时隙的状态

getTransactionsForAddress

查找要检查的交易对应的时隙和 transactionIndex

getTokenAccountsByOwnerV2

分页获取钱包当前的代币账户

请求参数

string
必填
拥有这些代币账户的钱包的 Base-58 编码地址。请传入所有者钱包,而不是代币账户。
number
要读取状态的时隙。返回该时隙结束时的账户状态。最早支持的时隙是 444959999,即纪元 1030 开始时的状态。省略时,将读取最新的已索引时隙,但不超过所请求确认级别允许的范围。
number
交易在时隙内的位置。返回该交易执行后立即呈现的账户状态,而不是时隙结束时的状态。必须同时提供 slot。
string
仅返回此铸币的代币账户。不能与 programId 同时使用。
string
仅返回所有者为此代币程序的代币账户。不能与 mint 同时使用。
  • TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
  • TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
string
默认值:"base64"
账户数据的编码格式。使用 jsonParsed 时,代币数量会采用铸币在请求位置时的小数位数。不支持 base58 和 binary。
  • base64
  • base64+zstd
  • jsonParsed
object
仅返回每个账户数据的一个切片。适用于 base64 和 base64+zstd 编码。
number
必填
开始读取位置的字节偏移量。
number
必填
要返回的字节数。
number
默认值:"5000"
要返回的代币账户数量上限(1-5,000)。
string
上一个响应的 paginationKey 游标,格式为 &lt;mint&gt;:&lt;tokenAccount&gt;。如果同时设置 mint,游标中的铸币必须与其匹配。
string
默认值:"finalized"
确认级别。不支持 processed。
  • finalized
  • confirmed
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>
默认值:getHistoricalTokenAccountsByOwner
必填

要调用的 RPC 方法名称。

可用选项:
getHistoricalTokenAccountsByOwner
示例:

"getHistoricalTokenAccountsByOwner"

params
(string | 查询 · object | 配置 · object)[]
必填

包含所有者钱包地址、用于选择历史位置的可选查询对象和可选配置对象的数组。

Required array length: 1 - 3 elements

拥有这些代币账户的钱包的 Base-58 编码地址。请传入所有者钱包,而不是代币账户。

示例:

"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"

响应

已成功检索一页历史代币账户。

jsonrpc
enum<string>

JSON-RPC 协议版本。

可用选项:
2.0
示例:

"2.0"

id
string

与请求匹配的标识符。

示例:

"1"

result
object