> ## 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.
# Cómo usar getSignatureStatuses
> Conoce los casos de uso, ejemplos de código, parámetros de solicitud, estructura de respuesta y consejos de getSignatureStatuses.
El método RPC [`getSignatureStatuses`](https://www.helius.dev/docs/api-reference/rpc/http/getsignaturestatuses) te permite obtener el estado de procesamiento y confirmación de una lista de firmas de transacciones. Esto resulta útil para determinar si la red ha [procesado, confirmado o finalizado](https://www.helius.dev/blog/solana-commitment-levels) las transacciones.
A menos que la opción `searchTransactionHistory` esté habilitada, este método consulta principalmente una caché de estados recientes en el nodo RPC. Para transacciones más antiguas, es fundamental habilitar `searchTransactionHistory`.
**Evita agrupar solicitudes para mejorar el rendimiento**
Agrupar métodos de archivo aumenta considerablemente la latencia. No se permiten lotes de más de 10 solicitudes.
## Casos de uso comunes
* **Confirmar la finalidad de una transacción:** Verifica si una transacción enviada alcanzó el nivel de confirmación deseado (p. ej., `confirmed` o `finalized`).
* **Consultar estados por lotes:** Comprueba de forma eficiente el estado de varias transacciones a la vez, por ejemplo, después de un envío por lotes.
* **Actualizar la interfaz según el estado de la transacción:** Muestra al usuario el estado de una transacción en tiempo real.
* **Comprobar errores:** Identifica si alguna de las transacciones de una lista falló y por qué.
## Parámetros de la solicitud
1. **`signatures`** (`array` de `string`): (Obligatorio) Un arreglo de firmas de transacciones codificadas en base 58. Puedes consultar hasta 256 firmas en una sola solicitud.
2. **`options`** (`object`, opcional): Un objeto de configuración opcional con el siguiente campo:
* **`searchTransactionHistory`** (`boolean`, opcional): Si es `true`, el nodo RPC buscará las firmas en todo su historial de transacciones. Si es `false` (el valor predeterminado), solo buscará en una caché de estados recientes. Para transacciones antiguas o que podrían haberse descartado, establece este valor en `true`.
## Estructura de la respuesta
El campo `result` de la respuesta JSON-RPC contiene un objeto con dos campos:
* **`context`** (`object`): Un objeto que contiene:
* **`slot`** (`u64`): El slot en el que el nodo RPC procesó esta solicitud.
* **`value`** (`array` de `object` | `null`): Un arreglo de objetos de estado que corresponde al orden de las firmas en la solicitud. Cada elemento puede ser:
* Un **objeto** con los siguientes campos si se encuentra la firma:
* **`slot`** (`u64`): El slot en el que se procesó la transacción.
* **`confirmations`** (`number` | `null`): La cantidad de bloques confirmados desde que se procesó la transacción. Es `null` si la transacción está finalizada (como la finalidad implica que no se revertirá, una cantidad específica de confirmaciones no resulta tan relevante).
* **`err`** (`object` | `null`): Un objeto de error si la transacción falló (p. ej., `{"InstructionError":[0,{"Custom":1}]}`) o `null` si se completó correctamente.
* **`status`** (`object`): Un objeto que indica el estado de ejecución de la transacción. Por lo general, es `{"Ok":null}` para transacciones completadas correctamente o un objeto que detalla el error para las transacciones fallidas.
* **`confirmationStatus`** (`string` | `null`): El estado de confirmación del clúster para la transacción (p. ej., `processed`, `confirmed`, `finalized`). Puede ser `null` si el estado no está disponible en la caché y `searchTransactionHistory` es false.
* **`null`**: Si no se encuentra una firma en la caché de estados y `searchTransactionHistory` es `false` (o si realmente no existe ni siquiera al buscar en el historial).
## Ejemplos
### 1. Obtener el estado de una lista de firmas (caché reciente)
Este ejemplo obtiene el estado de dos firmas mediante la caché reciente del nodo.
```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. Obtener el estado mediante una búsqueda en el historial de transacciones
Este ejemplo obtiene el estado de varias firmas y solicita explícitamente al nodo que busque en su historial de transacciones.
```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();
```
## Consejos para desarrolladores
* **`searchTransactionHistory`:** Es fundamental para garantizar la fiabilidad. Si es `false` (valor predeterminado), el método solo consulta una caché reciente limitada. Si una transacción es antigua o pudo haberse descartado y no está en esta caché, devolverá `null` como estado de esa firma. Establécelo siempre en `true` si necesitas confirmar el estado de transacciones que podrían no ser muy recientes.
* **Límite de firmas:** Puedes consultar un máximo de 256 firmas por llamada.
* **Estado `null`:** Un valor `null` en el arreglo `value` para una firma determinada significa que no se encontró su estado. Esto podría deberse a que no está en la caché reciente (si `searchTransactionHistory` es false), a que la transacción nunca se incluyó o a que es demasiado antigua para el historial del nodo, incluso con `searchTransactionHistory: true`.
* **`confirmations: null`**: Esto suele significar que la transacción alcanzó el estado `finalized`. En este punto, el concepto de una cantidad específica de confirmaciones es menos relevante porque el bloque se considera irreversible.
* **Manejo de errores:** Revisa el campo `err` dentro de cada objeto de estado para comprobar si una transacción falló. El campo `status` también proporcionará detalles (p. ej., `{"Err":...}`).
Usar `getSignatureStatuses` es una forma eficiente de supervisar el estado de varias transacciones de Solana. Recuerda usar `searchTransactionHistory: true` para comprobar el estado de forma fiable.