Skip to main content

¿Por qué migrar?

La forma estándar de obtener el historial de transacciones de una dirección en Solana requiere dos pasos: llamar a getSignaturesForAddress para enumerar las firmas y, luego, llamar a getTransaction una vez por cada firma para obtener los detalles. Para 1,000 transacciones, eso equivale a 1,001 solicitudes HTTP. getTransactionsForAddress es un método RPC exclusivo de Helius que combina ambos pasos en una sola llamada. Devuelve hasta 1,000 transacciones completas por solicitud, con filtrado, ordenamiento bidireccional y compatibilidad con cuentas de tokens que los métodos estándar no ofrecen. El resultado: aproximadamente 10 veces menos créditos, 1,000 veces menos viajes de ida y vuelta, y sin procesamiento por lotes del lado del cliente, manejo de límites de frecuencia ni lógica de reintentos para la expansión de llamadas a getTransaction.

Antes y después

Esta es la misma tarea —obtener las últimas 1,000 transacciones de una dirección con todos sus detalles— con ambos patrones:
getTransactionsForAddress no forma parte del RPC estándar de Solana, por lo que @solana/web3.js no tiene un método auxiliar Connection para él. Llámalo con una solicitud JSON-RPC directa, como se muestra arriba. Funciona en el mismo endpoint de Helius que el resto de tu tráfico RPC.

Asignación de parámetros

Cada opción del flujo anterior de dos pasos tiene un equivalente directo. La mayoría de los nombres se mantienen sin cambios; solo la paginación funciona de forma diferente.

Desde getSignaturesForAddress

Desde getTransaction

Dos funcionalidades no tienen ningún equivalente anterior:
  • filters — limita los resultados por blockTime, slot, status, tokenTransfer o tokenAccounts del lado del servidor, en lugar de obtener todo y filtrarlo en tu código.
  • sortOrder: "asc" — resultados cronológicos (primero los más antiguos), que los métodos estándar no pueden devolver sin obtener todo el historial e invertirlo.

Pasos de migración

1

Confirm you're on a Helius endpoint

getTransactionsForAddress es exclusivo de Helius. Funciona en https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY (y en devnet), el mismo endpoint que ya usan tus llamadas existentes si eres cliente de Helius. No necesitas cambiar la clave de API ni el plan.
2

Replace the two-step fetch with one call

Elimina la llamada a getSignaturesForAddress y el bucle de getTransaction. Realiza una sola solicitud a getTransactionsForAddress con transactionDetails: "full" y conserva tus valores de encoding, maxSupportedTransactionVersion y commitment como se muestra en la asignación de parámetros.Si solo necesitas las firmas (por ejemplo, para alimentar un pipeline existente), usa transactionDetails: "signatures" en su lugar. Tiene un costo fijo de 10 créditos por llamada.
3

Update the response handling

La envoltura de la respuesta cambia de tres formas:
  • Los resultados se encuentran en result.data (un arreglo), no directamente en result.
  • Cada entrada del modo completo es { slot, transactionIndex, blockTime, transaction, meta }. Los objetos transaction e meta tienen una estructura idéntica a la que devuelve getTransaction, por lo que puedes conservar tu código de análisis sin cambios.
  • Las entradas del modo de firmas coinciden con la salida de getSignaturesForAddress (signature, slot, err, memo, blockTime, confirmationStatus), más un nuevo campo transactionIndex.
Ten en cuenta una diferencia de comportamiento: con el patrón anterior, una llamada a getTransaction podía devolver null para una firma. Con getTransactionsForAddress, cada entrada de result.data es una transacción completa. Elimina cualquier manejo de valores nulos para detalles faltantes.
4

Replace signature-based pagination

Sustituye el bucle del cursor before por paginationToken:
El bucle termina cuando paginationToken es null. Ya no necesitas comparar listas de firmas ni llevar el seguimiento de la última firma por tu cuenta.Si usabas until para detenerte en una firma conocida, reemplázalo con filters.signature: { gt: "KNOWN_SIGNATURE" }. Si lo usabas para detenerte en un momento determinado, filters.blockTime o filters.slot suele ser una opción más adecuada.
5

Optional: enable complete token history

El patrón anterior omite por completo la actividad de las cuentas de tokens asociadas (ATA), a menos que también llames a getTokenAccountsByOwner y obtengas las firmas de cada cuenta de tokens. Para incluirla, agrega un filtro:
balanceChanged devuelve transacciones que hacen referencia a la billetera o cambian el saldo de cualquier cuenta de tokens que le pertenezca, y excluye el spam. Consulta cuentas de tokens asociadas para conocer las opciones none/balanceChanged/all y la salvedad para datos anteriores a 2022.
6

Verify against the old output

Para una dirección de ejemplo, obtén el historial de ambas formas y compara los conjuntos de firmas. Si filters.tokenAccounts no está configurado (el valor predeterminado none), getTransactionsForAddress devuelve las mismas transacciones que getSignaturesForAddress para el mismo intervalo. Luego, implementa los cambios y elimina la ruta de código anterior.

Diferencias de comportamiento que debes revisar

La mayoría de las migraciones son reemplazos directos, pero revisa lo siguiente antes de publicar:
  • Commitment. processed no es compatible; usa confirmed o finalized. Si tu código anterior consultaba periódicamente el historial reciente con processed, cambia a confirmed.
  • Medición. Las respuestas de transacciones completas cuestan 10 créditos por cada 100 transacciones devueltas (con un mínimo de 10 créditos); las respuestas que solo contienen firmas tienen un costo fijo de 10 créditos. El patrón anterior costaba 1 crédito por llamada: era más barato por solicitud, pero mucho más caro por transacción obtenida. Las respuestas fallidas son gratuitas. Consulta medición.
  • Compatibilidad de red. Mainnet tiene retención ilimitada. Devnet es compatible y ofrece 2 semanas de retención. Testnet no es compatible.
  • Direcciones reservadas. Un conjunto pequeño de direcciones del sistema (Vote Program, System Program y sysvars) se dirige a rutas de archivo alternativas o devuelve resultados vacíos. Si las indexas, revisa limitaciones y casos extremos.
  • Varias direcciones. Al igual que en el flujo anterior, una solicitud cubre una dirección. Consulta las direcciones en paralelo y combina los resultados; consulta varias direcciones.

Preguntas frecuentes

¿Es getTransactionsForAddress un método RPC estándar de Solana?

No. Es un método exclusivo de Helius disponible en los endpoints RPC de Helius. El RPC estándar de Solana y otros proveedores solo ofrecen getSignaturesForAddress e getTransaction. Tus demás llamadas RPC no se ven afectadas: el método está disponible en el mismo endpoint junto con toda la superficie RPC estándar.

¿Todavía necesito getTransaction después de migrar?

Solo para consultas individuales en las que ya tienes una firma y no tienes el contexto de una dirección, como verificar una transacción específica que pegó un usuario. Para cualquier historial basado en direcciones —procesos de backfill, indexación o feeds de actividad de billeteras—, getTransactionsForAddress reemplaza ambos métodos.

¿Funciona con @solana/web3.js?

El método no está en la clase Connection, pero funciona con cualquier cliente HTTP que se conecte a tu URL RPC de Helius. Usa fetch (o el equivalente de tu lenguaje) con un cuerpo JSON-RPC estándar, como se muestra en los ejemplos anteriores. Puedes seguir usando Connection para todo lo demás.

¿Devolverá las mismas transacciones que getSignaturesForAddress?

Sí. Con la configuración predeterminada (filters.tokenAccounts: "none"), devuelve las transacciones que hacen referencia a la dirección consultada: el mismo conjunto que getSignaturesForAddress. Si estableces tokenAccounts en balanceChanged o all, devuelve más resultados: agrega la actividad de las cuentas de tokens asociadas de la billetera, que el método estándar no puede detectar.

¿Cuánto cuesta en comparación con el patrón anterior?

Obtener 1,000 transacciones completas cuesta 100 créditos con getTransactionsForAddress, frente a aproximadamente 1,001 créditos (y 1,001 solicitudes) con getSignaturesForAddress + getTransaction. Las respuestas que solo contienen firmas tienen un costo fijo de 10 créditos por llamada. Consulta créditos de Helius para ver todos los precios.

Deja que un agente de IA realice la migración

Si usas Claude Code, Cursor u otro agente de programación, pega el siguiente prompt en la sesión del agente de tu repositorio. Encontrará el patrón anterior en tu código base y lo reescribirá.
El prompt es autocontenido: el agente no necesita acceso a esta página. Para consultar documentación preparada para agentes, búsqueda mediante MCP y habilidades, consulta Helius para agentes de IA.

Próximos pasos

getTransactionsForAddress guide

Tutorial completo sobre filtros, ordenamiento, paginación y cuentas de tokens.

API reference

Esquema completo de solicitudes y respuestas.

Indexing guide

Usa getTransactionsForAddress para realizar el backfill y sincronizar un índice de Solana.

Historical data overview

Compara todos los métodos de datos históricos de Solana.