为什么迁移?
在 Solana 上获取地址的交易历史的标准方法需要两个步骤:调用getSignaturesForAddress 列出签名,然后每个签名调用 getTransaction 获取详细信息。对于 1,000 笔交易,需要 1,001 个 HTTP 请求。
getTransactionsForAddress 是 Helius 专属的 RPC 方法,将这两步合并为一个调用。每次请求最多返回 1,000 笔完整交易,具有标准方法不具备的过滤、双向排序和代币账户支持。
结果:大约减少 10 倍的信用,减少 1,000 倍的往返次数,并且对于
getTransaction 的分散没有客户端批处理、速率限制处理或重试逻辑。
前后对比
以下是在两种模式下执行相同的任务 —— 获取地址的最后 1,000 笔交易的完整详细信息:getTransactionsForAddress 不属于标准 Solana RPC,因此 @solana/web3.js 没有 Connection 的辅助工具。按上述示例通过原始 JSON-RPC 请求调用它 —— 它在与您其他 RPC 流量相同的 Helius 端点上运行。
参数映射
旧的两步流程中的每个选项都有直接对应的等效项。大多数名称保持不变 —— 只有分页方式不同。来源自 getSignaturesForAddress
来源自 getTransaction
两个功能完全没有旧等效项:
filters— 用blockTime、slot、status、tokenTransfer或tokenAccounts服务器端细分结果,而不是在代码中获取所有内容并过滤。sortOrder: "asc"— 按时间顺序(最旧的优先)的结果,标准方法无法在不获取整个历史记录并反转的情况下返回。
迁移步骤
1
确认您在 Helius 端点上
getTransactionsForAddress 是 Helius 专属。它可以在 https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY(和 devnet)上工作 —— 如果您是 Helius 客户,现有调用的端点已使用。所以不需要更改 API 密钥或计划。2
将两步获取替换为一次调用
删除
getSignaturesForAddress 调用和 getTransaction 循环。使用 transactionDetails: "full" 进行单个 getTransactionsForAddress 请求,同时继承您的 encoding、maxSupportedTransactionVersion 和 commitment 值,如 参数映射 中所示。如果您只需要签名(例如,用于现有管道),请改用 transactionDetails: "signatures" —— 每次调用费用为 10 个信用。3
更新响应处理
响应封套有三个变化:
- 结果存在于
result.data(一个数组)中,而不是直接存在于result中。 - 每个完整模式条目是
{ slot, transactionIndex, blockTime, transaction, meta }。transaction和meta对象在形状上与getTransaction返回的结果相同,因此您的解析代码可以不变。 - 签名模式条目匹配
getSignaturesForAddress输出(signature,slot,err,memo,blockTime,confirmationStatus)加上一个新的transactionIndex字段。
getTransaction 调用可能会为一个签名返回 null。使用 getTransactionsForAddress 时,每个 result.data 条目都是一个完整的交易 —— 请删除任何用于处理缺失详细信息的空值处理。4
替换基于签名的分页
将 循环在
before 游标循环替换为 paginationToken:paginationToken 是 null 时结束 —— 不再需要比较签名列表或自行跟踪最后一个签名。如果您使用 until 停止在已知的签名处,则将其替换为 filters.signature: { gt: "KNOWN_SIGNATURE" }。如果您用于在某个时间点停止,filters.blockTime 或 filters.slot 通常更适合。5
可选:启用完整的代币历史
除非您还调用
getTokenAccountsByOwner 并获取每个代币账户的签名,否则旧模式会错过关联代币账户(ATA)活动。要包括它,请添加一个过滤器:balanceChanged 返回引用钱包或更改其拥有的任何代币账户余额的交易,过滤掉垃圾邮件。请参阅 关联代币账户 以获取 none/balanceChanged/all 选项和 2022 年前的注意事项。6
验证旧输出
对于示例地址,通过两种方式获取历史记录并比较签名集。在
filters.tokenAccounts 未设置(默认 none)的情况下,getTransactionsForAddress 返回与同一范围的 getSignaturesForAddress 相同的交易。然后部署并移除旧代码路径。行为差异审查
大多数迁移是直接替换,但在发布前检查以下内容:- 承诺。 不支持
processed;使用confirmed或finalized。如果您的旧代码轮询processed的最近历史,请切换到confirmed。 - 计量。 完整交易响应每 100 笔交易返回的费用为 10 个信用(最低 10 个信用);仅签名的响应每次调用固定花费 10 个信用。旧模式每次调用费用为 1 个信用 —— 每次请求便宜,但每笔交易获取的费用大大增加。失败的响应是免费的。请参阅 计量。
- 网络支持。 主网具有无限保留。Devnet 支持两周的保留。Testnet 不支持。
- 保留地址。 一小部分系统地址(投票程序、系统程序、sysvars)路由到备份归档路径或返回为空。如果您索引这些,请审查 限制和边界情况。
- 多个地址。 像旧流程一样,一次请求涵盖一个地址。并行查询地址并合并;请参阅 多个地址。
常见问题
getTransactionsForAddress 是标准的 Solana RPC 方法吗?
不是。它是 Helius 专属方法,仅在 Helius RPC 端点上提供。标准 Solana RPC 和其他提供者只提供getSignaturesForAddress 和 getTransaction。您的其他 RPC 调用不受影响 —— 此方法与完整的标准 RPC 界面一起存在于同一端点上。
迁移后我还需要 getTransaction 吗?
仅用于您已经拥有签名且没有地址上下文的一次性查找,例如验证用户粘贴的特定交易。对于任何基于地址的历史记录 —— 回填、索引、钱包活动提要 ——getTransactionsForAddress 替代这两种方法。
它能与 @solana/web3.js 一起使用吗?
该方法不在Connection 类中,但可以通过任何 HTTP 客户端对您的 Helius RPC URL 进行调用。使用 fetch(或您语言的等效工具)按上述示例使用标准 JSON-RPC 主体。您可以继续将 Connection 用于其他操作。
它会返回与 getSignaturesForAddress 相同的交易吗?
是的。使用默认设置(filters.tokenAccounts: "none"),它返回引用查询地址的交易 —— 与 getSignaturesForAddress 返回的集合相同。将 tokenAccounts 设置为 balanceChanged 或 all 返回更多:它添加了钱包的关联代币账户的活动,这是标准方法无法看到的。
它的费用与旧模式相比如何?
使用getTransactionsForAddress 获取 1,000 笔完整交易的费用为 100 个信用,而使用 getSignaturesForAddress + getTransaction 的费用约为 1,001 个信用(和 1,001 个请求)。仅签名的响应每次调用固定费用 10 个信用。请参阅 Helius 费用 获取完整定价。
让 AI 代理执行迁移
如果您使用 Claude Code、Cursor 或其他编码代理,请将下面的提示粘贴到代码库的代理会话中。它会在您的代码库中找到旧模式并重写。后续步骤
getTransactionsForAddress 指南
全面教程,涵盖过滤器、排序、分页和代币账户。
API 参考
完整的请求和响应模式。
索引指南
使用 getTransactionsForAddress 进行回填和同步 Solana 索引。
历史数据概览
比较所有 Solana 历史数据方法。