Token Account (ATA) Filtering over WebSocket

The tokenAccounts filter on the transactionSubscribe WebSocket method lets a subscription match activity on the associated token accounts (ATAs) a wallet owns, not just transactions where the wallet’s pubkey appears directly. The same filter is available over gRPC — see Token Account (ATA) Filtering for the gRPC version.

The problem: plain account filters miss incoming token transfers

When you watch a wallet with accountInclude: [wallet], you only match transactions where that wallet pubkey appears in the transaction’s account keys. A common case slips through: when someone sends the wallet an SPL token (USDC, for example), the transfer touches the wallet’s associated token account (ATA) — a separate program-derived address — not the wallet pubkey itself. So a plain accountInclude: [wallet] subscription never sees incoming token transfers. You would have to enumerate every ATA the wallet owns up front and add each one to the filter — but ATAs are created on demand (one per mint), so you can’t know the full set in advance.

How `tokenAccounts` expansion works

Set tokenAccounts on the subscription to expand matching so an accountInclude wallet also matches transactions that touch a token account it owns. Matching is owner-based: LaserStream resolves the token accounts owned by your accountInclude addresses at match time, so it catches any token account the wallet owns — including non-canonical ones — not just the derived ATA address. You never have to list the ATAs yourself. Subscriptions that omit tokenAccounts behave exactly as before, so it’s safe to add to an existing filter.

Expansion modes

tokenAccounts takes one of three string values:

Value	Matches	Volume	Use it for
`"balanceChanged"`	Transactions where an owned token balance actually changed (or its token account was closed)	Lower — the recommended default	”Tell me when money actually moved” — deposits, withdrawals, swaps that settle to the wallet
`"all"`	Any transaction that references a token account the wallet owns, even if the balance didn’t change	Higher	Full visibility into anything that so much as touches the wallet’s token accounts
`"none"`	No expansion — identical to omitting the field	—	The default

Start with "balanceChanged". It captures real fund movement at a fraction of the volume of "all".

Use it in `transactionSubscribe`

tokenAccounts is a Helius extension to the standard Solana WebSocket API. An invalid value returns JSON-RPC error -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: 0 }
    ]
  }));
  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);
});

Reading what matched

Once a transaction matches via ATA expansion, the wallet’s token movement lives in the transaction’s meta.postTokenBalances and meta.preTokenBalances. Filter those entries by owner to isolate the balances your wallet actually owns, then diff preTokenBalances against postTokenBalances on the same accountIndex to see how much each mint moved. The example above shows the filtering step.

transactionSubscribe

Every transactionSubscribe filter and option, including tokenAccounts.

Token Account Filtering (gRPC)

The same tokenAccounts expansion on LaserStream gRPC transaction filters.

notifyOn Filtering

Skip no-op account updates on accountSubscribe and programSubscribe.

WebSocket Quickstart

Connect to LaserStream WebSocket and stream your first events.

Get Started

Data Streaming & Event Listening

Data APIs & RPCs

Trading

Sending Transactions

Wallet-as-a-Service

Guides

Resources

Token Account (ATA) Filtering over WebSocket

The problem: plain account filters miss incoming token transfers

How `tokenAccounts` expansion works

Expansion modes

Use it in `transactionSubscribe`

Reading what matched

transactionSubscribe

Token Account Filtering (gRPC)

notifyOn Filtering

WebSocket Quickstart

​The problem: plain account filters miss incoming token transfers

​How tokenAccounts expansion works

​Expansion modes

​Use it in transactionSubscribe

​Reading what matched

​Related

transactionSubscribe

Token Account Filtering (gRPC)

notifyOn Filtering

WebSocket Quickstart

The problem: plain account filters miss incoming token transfers

How `tokenAccounts` expansion works

Expansion modes

Use it in `transactionSubscribe`

Reading what matched

Related