Skip to main content
Streams a holder’s row on a token each time a trade or transfer changes it. Subscribe on an open stream connection. See WebSocket streams for connections, frames and reconnection.

​
Filters

​
string
required
Chain slug of the token.
​
string
required
Token address on chain. The subscription uses one unit of the address limit.
​
string[]
Wallet classifications to match, using the same values as the Token holders flags parameter. A holder matches when it carries at least one of them, and fomo matches wallets flagged fomo. Omit it to match every holder. On a busy token, most trades change a holder, so flags reduces the number of updates.
This channel does not accept throttleMs and does not send exit frames.

​
Message format

Each update’s data is one holder’s full row on the token after a change, in the same row shape that Token holders returns, without rank. Its trading figures cover the lifetime period.
  • Keep one row per chain, token and address; a later update replaces the earlier one.
  • Rank the rows by balance on the client, largest first.
  • A holder that sells its entire balance is sent with a balance of 0. Remove it from the list.
Rows do not include value or unrealized PnL. To price a row, use the formulas on Token holders.

​
Initial snapshot

  1. Subscribe.
  2. Read Token holders with the same flags and period=lifetime.
  3. Merge the REST response and the updates on address.
The REST response returns at most 150 holders, while the stream sends every holder that changes. A holder missing from the REST response can therefore appear on the stream, so rank the merged rows by balance. Repeat the REST request after every reconnect.

​
Errors