如何使用 getSignatureStatuses

​

常见用例

• 确认交易最终性： 验证已提交的交易是否已达到所需的确认级别（例如，confirmed 或 finalized）。
• 批量状态查询： 高效地一次检查多个交易的状态，例如，在批量发送后。
• 根据交易状态更新UI： 向用户反映交易的实时状态。
• 错误检查： 确定列表中的任何交易是否失败以及原因。

​

请求参数

1. signatures (array of string): （必需）一个base-58编码的交易签名数组。您可以在单个请求中查询最多256个签名。
2. options (object, 可选): 一个可选的配置对象，包含以下字段：

• searchTransactionHistory (boolean, 可选): 如果是 true，RPC节点将搜索其完整的交易历史以查找签名。如果是 false（默认），则仅搜索最近的状态缓存。对于旧的或可能被丢弃的交易，将此设置为 true。

​

响应结构

• context (object): 一个包含以下内容的对象：
• slot (u64): RPC节点处理此请求的槽位。
• value (array of object | null): 一个状态对象数组，对应于请求中签名的顺序。每个元素可以是：
• 如果找到签名，则为包含以下字段的对象：
• slot (u64): 交易被处理的槽位。
• confirmations (number | null): 自交易处理以来已确认的区块数。如果交易已完成，则为null（因为最终性意味着它不会被回滚，因此具体的确认计数不那么相关）。
• err (object | null): 如果交易失败，则为错误对象（例如，{"InstructionError":[0,{"Custom":1}]}），如果成功则为null。
• status (object): 一个指示交易执行状态的对象。通常为成功交易的{"Ok":null}或详细说明错误的对象。
• confirmationStatus (string | null): 集群对交易的确认状态（例如，processed, confirmed, finalized）。如果状态在缓存中不可用且searchTransactionHistory为false，则可以为null。
• null: 如果在状态缓存中找不到签名且searchTransactionHistory为false（或即使进行历史搜索也确实不存在）。

​

示例

​

1. 获取签名列表的状态（最近缓存）

# Replace <api-key> with your Helius API key
# Replace with actual transaction signatures
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSignatureStatuses",
    "params": [
      [
        "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
        "2x5YfV29N4p9K2kEFK2gFfC5T5acbs2z2MytTZqrgq17pYjCMfYjW4sAUpkWMkMzxGztD2Qv5v7n92uYJcQY9c7a" 
      ]
    ]
  }'

​

2. 使用交易历史搜索获取状态

# Replace <api-key> with your Helius API key
# Replace with actual transaction signatures
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSignatureStatuses",
    "params": [
      [
        "3jPTfHcbzWHeD4jW8q4Y8g3h2D1aBwM81y1sHhDqYQ7Z9x5n7cVy2gD8QWbK9eXwSjJ6aA7FzV2kLpQoEwU9jX", 
        "4SyzjM2fTALqTNjLKMM1yG1bW7kCFu2GvEkKcvKChG9o1KjQW8jLdZ6sWfN9mP1pU3rD7XvA6B2CjHkLwRzYxTnX"  
      ],
      {
        "searchTransactionHistory": true
      }
    ]
  }'

​

开发者提示

• searchTransactionHistory: 对于可靠性至关重要。如果 false（默认），该方法仅检查有限的最近缓存。如果交易较旧或可能被丢弃且不在此缓存中，它将返回该签名状态的 null。如果需要确认可能不是非常近期的交易状态，请始终设置为 true。
• 签名限制： 每次调用最多可以查询256个签名。
• null 状态： 给定签名的 value 数组中的 null 表示未找到其状态。这可能是因为它不在最近缓存中（如果 searchTransactionHistory 为 false），交易从未落地，或者即使使用 searchTransactionHistory: true 也太旧而无法在节点历史中找到。
• confirmations: null: 这通常意味着交易已达到 finalized 状态。此时，特定确认次数的概念不再那么重要，因为区块被认为是不可逆的。
• 错误处理： 检查每个状态对象中的 err 字段以查看交易是否失败。status 字段也将提供详细信息（例如，{"Err":...}）。