> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metastreams.io/llms.txt
> Use this file to discover all available pages before exploring further.

# spot.holders

> Streams a token's holder rows each time a trade or transfer changes them.

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](https://docs.metastreams.io/streams/overview.md) for connections, frames and reconnection.

## Filters

**chain** `string` *required*

[Chain slug](https://docs.metastreams.io/concepts/chains.md) of the token.

**token** `string` *required*

Token address on `chain`. The subscription uses one unit of the [address limit](https://docs.metastreams.io/streams/filters.md#address-limits).

**flags** `string[]`

[Wallet classifications](https://docs.metastreams.io/resources/glossary.md#wallet-classifications) to match, using the same values as the [Token holders](https://docs.metastreams.io/reference/rest/token-holders.md#filters) `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](https://docs.metastreams.io/reference/rest/token-holders.md) 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](https://docs.metastreams.io/reference/rest/token-holders.md#response).

## Initial snapshot

1. Subscribe.
2. Read [Token holders](https://docs.metastreams.io/reference/rest/token-holders.md) 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

| Code | When |
| - | - |
| `VALIDATION_ERROR` | Missing `chain` or `token`; a token address in the wrong format for the chain; an unknown flag; an unknown filter field; an exceeded [address limit](https://docs.metastreams.io/streams/filters.md#address-limits) |
| `UNSUPPORTED_CHAIN` | Unsupported `chain` slug |

```json Subscribe theme={null}
{
  "action": "subscribe",
  "channel": "spot.holders",
  "filters": {
    "chain": "solana",
    "token": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "flags": ["bundler", "insider"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.