> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 如何使用 getSignatureStatuses
> 了解 getSignatureStatuses 的使用案例、代码示例、请求参数、响应结构和提示。
[此处的RPC方法](https://www.helius.dev/docs/api-reference/rpc/http/getsignaturestatuses)允许您检索一组交易签名的处理和确认状态。这对于确定交易是否已被网络[处理、确认或完成](https://www.helius.dev/blog/solana-commitment-levels)很有用。
除非启用选项，否则此方法主要查询RPC节点上的最近状态缓存。对于较旧的交易，启用此选项至关重要。
**避免批处理以提高性能**
批处理归档方法会显著增加延迟。不允许超过10个请求的批处理。
## 常见用例
* **确认交易的最终性：** 验证提交的交易是否已达到所需的确认级别（例如，或）。
* **批量状态查询：** 高效地一次检查多个交易的状态，例如在批量发送之后。
* **根据交易状态更新UI：** 向用户显示交易的实时状态。
* **错误检查：** 确认交易列表中是否有交易失败及原因。
## 请求参数
1. **（必需）**：Base-58编码的交易签名数组。您可以在单个请求中查询最多256个签名。
2. **（可选）：** 可选的配置对象，包含以下字段：
* **（可选）：** 如果为true，RPC节点将搜索其完整的交易历史记录以获取签名。如果为false（默认），则仅搜索最近的状态缓存。对于旧的或可能丢失的交易，请将其设置为true。
## 响应结构
JSON-RPC响应的字段包含一个对象，其中有两个字段：
* **：** 包含以下内容的对象：
* **：** RPC节点处理此请求的插槽。
* **：** 与请求中签名顺序相对应的状态对象数组。每个元素可以是：
* 如果找到签名的**对象**，包含以下字段：
* **：** 处理交易的插槽。
* **：** 自交易处理以来已确认的区块数。如果交易已完成，则为完成状态（因为完成意味着它不会被回滚，因此具体的确认数不那么相关）。
* **：** 如果交易失败的错误对象（例如，），或者如果成功则为空。
* **：** 指示交易执行状态的对象。通常为成功交易的简单确认或描述失败原因的详细对象。
* **：** 集群对交易的确认状态（例如，）。如果状态在缓存中不可用且为false，则为空。
* **：** 如果在状态缓存中找不到签名且为false（或即使历史搜索也确实不存在）。
## 示例
### 1. 获取签名列表的状态（最近缓存）
此示例获取两个签名的状态，依赖于节点的最近缓存。
```bash cURL theme={"system"}
# Replace with your Helius API key
# Replace with actual transaction signatures
curl https://mainnet.helius-rpc.com/?api-key= -X POST -H "Content-Type: application/json" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "getSignatureStatuses",
"params": [
[
"5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
"2x5YfV29N4p9K2kEFK2gFfC5T5acbs2z2MytTZqrgq17pYjCMfYjW4sAUpkWMkMzxGztD2Qv5v7n92uYJcQY9c7a"
]
]
}'
```
```javascript JavaScript (using @solana/web3.js) theme={"system"}
// Replace with your Helius API key
const { Connection } = require('@solana/web3.js');
async function checkRecentSignatures() {
const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=');
const signatures = [
'5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW',
'2x5YfV29N4p9K2kEFK2gFfC5T5acbs2z2MytTZqrgq17pYjCMfYjW4sAUpkWMkMzxGztD2Qv5v7n92uYJcQY9c7a' // Replace with another signature
];
try {
const response = await connection.getSignatureStatuses(signatures);
console.log("RPC Response Context Slot:", response.context.slot);
response.value.forEach((status, index) => {
console.log(`--- Status for Signature ${index + 1} (${signatures[index].substring(0,10)}...) ---`);
if (status) {
console.log(` Slot: ${status.slot}`);
console.log(` Confirmations: ${status.confirmations === null ? 'Finalized (or N/A)' : status.confirmations}`);
console.log(` Error: ${JSON.stringify(status.err)}`);
console.log(` Execution Status: ${JSON.stringify(status.status)}`);
console.log(` Confirmation Status: ${status.confirmationStatus}`);
} else {
console.log(' Status not found (likely not in recent cache or does not exist).');
}
});
} catch (error) {
console.error('Error fetching signature statuses:', error);
}
}
checkRecentSignatures();
```
### 2. 使用交易历史搜索获取状态
此示例获取签名的状态，并明确请求节点搜索其交易历史。
```bash cURL theme={"system"}
# Replace with your Helius API key
# Replace with actual transaction signatures
curl https://mainnet.helius-rpc.com/?api-key= -X POST -H "Content-Type: application/json" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "getSignatureStatuses",
"params": [
[
"3jPTfHcbzWHeD4jW8q4Y8g3h2D1aBwM81y1sHhDqYQ7Z9x5n7cVy2gD8QWbK9eXwSjJ6aA7FzV2kLpQoEwU9jX",
"4SyzjM2fTALqTNjLKMM1yG1bW7kCFu2GvEkKcvKChG9o1KjQW8jLdZ6sWfN9mP1pU3rD7XvA6B2CjHkLwRzYxTnX"
],
{
"searchTransactionHistory": true
}
]
}'
```
```javascript JavaScript (using @solana/web3.js) theme={"system"}
// Replace with your Helius API key
const { Connection } = require('@solana/web3.js');
async function checkSignaturesWithHistory() {
const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=');
const signatures = [
// Replace with a signature you know is older or might have been dropped
'3jPTfHcbzWHeD4jW8q4Y8g3h2D1aBwM81y1sHhDqYQ7Z9x5n7cVy2gD8QWbK9eXwSjJ6aA7FzV2kLpQoEwU9jX',
// Replace with another valid signature
'4SyzjM2fTALqTNjLKMM1yG1bW7kCFu2GvEkKcvKChG9o1KjQW8jLdZ6sWfN9mP1pU3rD7XvA6B2CjHkLwRzYxTnX'
];
try {
const response = await connection.getSignatureStatuses(signatures, { searchTransactionHistory: true });
console.log("RPC Response Context Slot:", response.context.slot);
response.value.forEach((status, index) => {
console.log(`--- Status for Signature ${index + 1} (${signatures[index].substring(0,10)}...) ---`);
if (status) {
console.log(` Slot: ${status.slot}`);
console.log(` Confirmations: ${status.confirmations === null ? 'Finalized (or N/A)' : status.confirmations}`);
console.log(` Error: ${JSON.stringify(status.err)}`);
console.log(` Execution Status: ${JSON.stringify(status.status)}`);
console.log(` Confirmation Status: ${status.confirmationStatus}`);
} else {
console.log(' Status not found (even with history search, it might not exist or is too old).');
}
});
} catch (error) {
console.error('Error fetching signature statuses with history:', error);
}
}
checkSignaturesWithHistory();
```
## 开发者提示
* **`searchTransactionHistory`:** 对于可靠性至关重要。如果 `false`（默认），方法只检查一个有限的最近缓存。如果交易过旧或可能被删除且不在此缓存中，它将返回该签名状态的 `null`。如果需要确认可能不太新的交易状态，请始终设置为 `true`。
* **签名限制：** 每次调用最多可以查询256个签名。
* **`null` 状态：** 给定签名的 `value` 数组中的 `null` 表示未找到其状态。这可能是因为它不在最近缓存中（如果 `searchTransactionHistory` 为假），交易从未提交，或者即使在 `searchTransactionHistory: true` 下也过于陈旧。
* **`confirmations: null`：** 这通常意味着交易已达到 `finalized` 状态。在这一点上，特定确认次数的概念不太相关，因为该区块被认为是不可逆的。
* **错误处理：** 检查每个状态对象内的 `err` 字段以查看交易是否失败。`status` 字段还将提供详细信息（例如，`{"Err":...}`）。
使用 `getSignatureStatuses` 是监控多个 Solana 交易状态的有效方式。记得使用 `searchTransactionHistory: true` 进行稳健的状态检查。