Filtrado de cuentas de tokens (ATA) mediante WebSocket

El filtro tokenAccounts del método WebSocket transactionSubscribe permite que una suscripción detecte actividad en las cuentas de tokens asociadas (ATA) que posee una billetera, no solo transacciones donde aparece directamente la clave pública de la billetera. El mismo filtro está disponible mediante gRPC. Consulta Filtrado de cuentas de tokens (ATA) para ver la versión de gRPC.

El problema: los filtros de cuentas simples omiten las transferencias de tokens entrantes

Cuando supervisas una billetera con accountInclude: [wallet], solo detectas las transacciones en las que la clave pública de esa billetera aparece entre las claves de cuenta de la transacción. Un caso común pasa inadvertido: cuando alguien envía un token SPL (por ejemplo, USDC) a la billetera, la transferencia interactúa con la cuenta de tokens asociada (ATA) de la billetera —una dirección independiente derivada por el programa—, no con la propia clave pública de la billetera. Por lo tanto, una suscripción simple con accountInclude: [wallet] nunca detecta las transferencias de tokens entrantes. Tendrías que enumerar de antemano todas las ATA que posee la billetera y agregar cada una al filtro. Sin embargo, las ATA se crean bajo demanda (una por cada mint), por lo que no puedes conocer el conjunto completo con anticipación.

Cómo funciona la expansión de `tokenAccounts`

Configura tokenAccounts en la suscripción para ampliar las coincidencias, de modo que una billetera indicada en accountInclude también detecte transacciones que interactúan con una cuenta de tokens que posee. La coincidencia se basa en el propietario: LaserStream resuelve, en el momento de buscar coincidencias, las cuentas de tokens que poseen tus direcciones de accountInclude. De este modo, detecta cualquier cuenta de tokens que posea la billetera, incluidas las no canónicas, y no solo la dirección ATA derivada. Nunca tienes que enumerar las ATA por tu cuenta. Las suscripciones que omiten tokenAccounts se comportan exactamente igual que antes, por lo que puedes agregarlo de forma segura a un filtro existente.

Modos de expansión

tokenAccounts acepta uno de estos tres valores de cadena:

Valor	Coincidencias	Volumen	Úsalo para
`"balanceChanged"`	Transacciones en las que cambió realmente el saldo de un token que posee la billetera (o se cerró su cuenta de tokens)	Menor — la opción predeterminada recomendada	«Avísame cuando los fondos se muevan realmente»: depósitos, retiros y swaps que se liquidan en la billetera
`"all"`	Cualquier transacción que haga referencia a una cuenta de tokens que posee la billetera, incluso si el saldo no cambió	Mayor	Visibilidad completa de cualquier operación que siquiera interactúe con las cuentas de tokens de la billetera
`"none"`	Sin expansión; equivale a omitir el campo	—	Opción predeterminada

Comienza con "balanceChanged". Captura movimientos reales de fondos con una fracción del volumen de "all".

Úsalo en `transactionSubscribe`

tokenAccounts es una extensión de Helius para la API WebSocket estándar de Solana. Un valor no válido devuelve el error JSON-RPC -32602: Invalid tokenAccounts value '<x>', expected one of: none, balanceChanged, all.

const ws = new WebSocket('wss://mainnet.helius-rpc.com/?api-key=<API_KEY>');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'transactionSubscribe',
    params: [
      {
        accountInclude: ['<WALLET_PUBKEY>'],
        tokenAccounts: 'balanceChanged' // also match the wallet's ATAs
      },
      { commitment: 'confirmed', encoding: 'jsonParsed', maxSupportedTransactionVersion: 1 }
    ]
  }));
  setInterval(() => ws.ping(), 30_000);
});

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  const result = msg.params?.result;
  if (!result) return;
  // Token balances this wallet owns that changed in the tx
  const owned = (result.transaction.meta.postTokenBalances || [])
    .filter((b) => b.owner === '<WALLET_PUBKEY>');
  console.log(result.signature, owned);
});

Cómo interpretar la coincidencia

Cuando una transacción coincide mediante la expansión de ATA, el movimiento de tokens de la billetera aparece en los campos meta.postTokenBalances e meta.preTokenBalances de la transacción. Filtra esas entradas por owner para aislar los saldos que realmente posee tu billetera. Luego, compara preTokenBalances con postTokenBalances en el mismo accountIndex para ver cuánto se movió cada mint. El ejemplo anterior muestra el paso de filtrado.

Contenido relacionado

transactionSubscribe

Todos los filtros y opciones de transactionSubscribe, incluido tokenAccounts.

Token Account Filtering (gRPC)

La misma expansión de tokenAccounts en los filtros de transacciones de LaserStream mediante gRPC.

WebSocket Quickstart

Conéctate a LaserStream WebSocket y transmite tus primeros eventos.

Primeros pasos

Streaming de datos y escucha de eventos

API de datos y RPC

Trading

Envío de transacciones

Billetera como servicio

Privacidad

Recursos

Filtrado de cuentas de tokens (ATA) mediante WebSocket

El problema: los filtros de cuentas simples omiten las transferencias de tokens entrantes

Cómo funciona la expansión de `tokenAccounts`

Modos de expansión

Úsalo en `transactionSubscribe`

Cómo interpretar la coincidencia

Contenido relacionado

transactionSubscribe

Token Account Filtering (gRPC)

WebSocket Quickstart

​El problema: los filtros de cuentas simples omiten las transferencias de tokens entrantes

​Cómo funciona la expansión de tokenAccounts

​Modos de expansión

​Úsalo en transactionSubscribe

​Cómo interpretar la coincidencia

​Contenido relacionado

transactionSubscribe

Token Account Filtering (gRPC)

WebSocket Quickstart

El problema: los filtros de cuentas simples omiten las transferencias de tokens entrantes

Cómo funciona la expansión de `tokenAccounts`

Modos de expansión

Úsalo en `transactionSubscribe`

Cómo interpretar la coincidencia

Contenido relacionado