Skip to main content

¿Qué es transactionSubscribe?

El método WebSocket transactionSubscribe (una extensión de Helius para la API WebSocket estándar de Solana) habilita eventos de transacciones en tiempo real. Para usarlo, proporciona un TransactionSubscribeFilter y, si lo deseas, incluye TransactionSubscribeOptions para personalizarlo aún más. transactionSubscribe se encuentra en los mismos puntos de conexión unificados wss://mainnet.helius-rpc.com e wss://devnet.helius-rpc.com que los métodos de suscripción estándar de Solana.

TransactionSubscribeFilter

  • vote: indicador booleano para incluir o excluir transacciones relacionadas con votos
  • failed: indicador booleano para incluir o excluir transacciones fallidas
  • signature: filtra las actualizaciones de una transacción específica según su firma
  • accountInclude: lista de cuentas de las que quieres recibir actualizaciones de transacciones. Solo una de las cuentas debe estar incluida en las actualizaciones de transacciones (p. ej., cuenta 1 O 2).
  • accountExclude: lista de cuentas que quieres excluir de las actualizaciones de transacciones
  • accountRequired: las transacciones deben incluir todas las cuentas especificadas para aparecer en las actualizaciones (p. ej., cuenta 1 Y 2)
  • tokenAccounts: expansión opcional de cuentas de tokens asociadas (ATA) (balanceChanged, all o none). Consulta Monitorear una billetera, incluidas las transferencias de tokens a continuación.
Puedes incluir hasta 50,000 direcciones en los arreglos accountInclude, accountExclude e accountRequired.

TransactionSubscribeOptions (Opcional)

  • commitment: nivel de compromiso para obtener datos (processed, confirmed o finalized)
  • encoding: formato de codificación de los datos devueltos (base58, base64 o jsonParsed)
  • transactionDetails: nivel de detalle de los datos devueltos (full, signatures, accounts e none)
  • showRewards: indicador booleano que señala si los datos de recompensas deben incluirse en las actualizaciones
  • maxSupportedTransactionVersion: especifica la versión más alta de las transacciones de las que quieres recibir actualizaciones. Establece el valor en 1 para recibir transacciones heredadas, v0 y v1. Consulta Compatibilidad con transacciones v1.
maxSupportedTransactionVersion es obligatorio para devolver las cuentas y los detalles completos de una transacción determinada (es decir, transactionDetails: "accounts" | "full").

Ejemplo de suscripción a transacciones

En este ejemplo, nos suscribimos a transacciones que contienen la cuenta de Raydium 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8. Cuando ocurra una transacción que contenga la cuenta 675k...1Mp8 en el accountKeys de la transacción, recibiremos una notificación WSS. Según las opciones de suscripción, la notificación de la transacción se enviará con el nivel de compromiso processed, la codificación jsonParsed y los detalles de transacción full, y mostrará las recompensas.

Notificación de ejemplo

Monitorear una billetera, incluidas las transferencias de tokens

Cuando monitoreas una billetera con accountInclude, solo se detectan las transacciones en las que la clave pública de la billetera aparece directamente en las claves de cuenta. Un caso frecuente no se detecta: cuando alguien envía un token SPL (por ejemplo, USDC) a la billetera, la transferencia afecta a la cuenta de token asociada (ATA) de la billetera, no a su clave pública, por lo que una suscripción básica accountInclude: [wallet] nunca la detecta. Configura el campo tokenAccounts para ampliar la detección, de modo que la cuenta monitoreada también coincida con transacciones en las que posee un saldo de tokens:
  • balanceChanged: detecta cuando la billetera posee un saldo de tokens cuyo importe cambió (o cuya cuenta de token se cerró) en la transacción. Úsalo para “avísame cuando el dinero realmente se mueva”. Esta es la opción más específica, de menor volumen y más común.
  • all: detecta cualquier transacción que haga referencia a un saldo de tokens que posee la billetera, incluso si no cambió. Genera un mayor volumen.
  • none: sin expansión. Equivale a omitir el campo (el valor predeterminado).
La detección se basa en el propietario: abarca cualquier cuenta de token que posea la billetera, incluidas las no canónicas, no solo la dirección ATA derivada. Un valor no válido devuelve el error JSON-RPC -32602. Las suscripciones que omiten tokenAccounts funcionan exactamente como antes. Para obtener una descripción completa de cómo funciona la expansión de ATA, consulta Filtrado de cuentas de tokens (ATA) mediante WebSocket.

Monitorear nuevos DCA de Jupiter

Jupiter DCA, o promedio de costo en dólares, es una forma de programar operaciones recurrentes en Solana. Como estas órdenes programadas de compra y venta se registran en la blockchain, los traders pueden usar el método transactionSubscribe y getAsset para detectar nuevas órdenes.

Notificación de ejemplo

Terminal tables of new Jupiter DCA orders showing the user wallet, token pair, open time, total input, amount per cycle, and interval

Monitorear nuevos tokens de pump.fun

Notificación de ejemplo

Terminal tables of newly created pump.fun tokens showing the transaction signature, creator wallet, and token mint address

Administrar suscripciones

Identificadores de suscripción

Cuando transactionSubscribe se ejecuta correctamente, el servidor devuelve un identificador de suscripción en el campo result. Es el mismo número que aparece en params.subscription en cada notificación de esa suscripción:
Guarda el identificador de suscripción de la respuesta. Lo necesitarás para cancelar la suscripción.

Cancelar la suscripción

Para dejar de recibir notificaciones, llama a transactionUnsubscribe con el identificador de suscripción. Cada llamada a transactionSubscribe en la misma conexión crea una suscripción independiente con su propio identificador. Asegúrate de cancelar la suscripción antes de volver a suscribirte para evitar recibir notificaciones duplicadas.
En este ejemplo, nos suscribimos a las transacciones de Raydium, obtenemos el identificador de suscripción de la respuesta del servidor y, luego, cancelamos la suscripción con ese identificador. Es posible que algunos mensajes en tránsito sigan llegando brevemente después de llamar a transactionUnsubscribe. Este comportamiento es normal.