> ## 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.

# wallet.balances

> Streams a wallet's new balance of an asset each time a transaction changes it.

Streams a wallet's updated balance of an asset each time a transaction 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 wallets' balances.

**wallets** `string[]` *required*

One or more wallet addresses on `chain`. For a single wallet, `wallet` with one address is also accepted. Each wallet uses one unit of the [address limit](https://docs.metastreams.io/streams/filters.md#address-limits).

To follow a wallet on multiple chains, open one subscription per chain.

## Message format

Each update's `data` is one wallet's balance of one asset after a transaction, not the change in balance. It has the same row shape that [Wallet balances](https://docs.metastreams.io/reference/rest/wallet-balances.md) returns.

Updates for one wallet can be delivered out of order, and some can be missed during a reconnect. Keep one row per `chain`, `wallet` and `asset`, choosing the row with the higher `blockNumber`, then the higher `txIndex`. Two rows with equal versions come from the same transaction, so either one is correct.

Rows are never retracted, even after a chain reorganization. Some changes, such as Solana rent and the fee of a failed transaction, produce no row, so a balance can lag until the wallet's next captured change.

## Initial snapshot

1. Subscribe.
2. Read [Wallet balances](https://docs.metastreams.io/reference/rest/wallet-balances.md) with the same wallets and `chains` set to the subscription's chain.
3. Merge the REST response and the updates using the rule above.

The REST response can lag the stream by a few seconds, so a change made just before subscribing can be missing from both. Read again a few seconds after subscribing, and again after every reconnect.

## Errors

| Code | When |
| - | - |
| `VALIDATION_ERROR` | Missing `chain`; no wallet; an address in the wrong format for the chain; 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": "wallet.balances",
  "filters": {
    "chain": "solana",
    "wallets": ["7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"]
  }
}
```

```json Update theme={null}
{
  "type": "update",
  "channel": "wallet.balances",
  "subscriptionId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "data": {
    "chain": "solana",
    "wallet": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5",
    "asset": "SOL",
    "balance": "41.208113",
    "trigger": "trade",
    "blockNumber": 371204118,
    "signature": "4xQmVb8e2kT1nR7pZcW3sLdHfA9jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h",
    "txIndex": 812,
    "updatedAt": 1789632015120
  }
}
```


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