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

# wallet.balances

> A wallet's new balance of an asset, each time a transaction moves it.

Subscribe on an open stream connection. See [Connecting to streams](/streams/overview) for the connection, frames and reconnecting.

## Filters

<ParamField body="chain" type="string" required>
  The [chain slug](/concepts/chains) the wallets hold balances on.
</ParamField>

<ParamField body="wallets" type="string[]" required>
  One or more wallet addresses on `chain`. For one wallet, you can send `wallet` with a single address instead. Each wallet spends one unit of the [address budget](/streams/filters#the-address-budget).
</ParamField>

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

## Update

Each update's `data` is one wallet's balance of one asset after a transaction, never the change. It has the row shape [Wallet balances](/reference/rest/wallet-balances) returns.

Updates for one wallet can arrive out of order, and a reconnect can miss some. Keep one row per `chain`, `wallet` and `asset`, and keep the row with the higher `blockNumber`, then the higher `txIndex`. Two rows with equal versions come from the same transaction, so either one serves.

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

## Snapshot, then stream

1. Subscribe.
2. Read [Wallet balances](/reference/rest/wallet-balances) with the same wallets and `chains` set to the subscription's chain.
3. Merge the read and the updates by the rule above.

The read can trail the stream by a few seconds, so a change made just before you subscribe can appear in neither. Read again a few seconds after you subscribe, and again after every reconnect.

## Errors

| Code | When |
| - | - |
| `VALIDATION_ERROR` | `chain` missing; no wallet; an address in the wrong format for the chain; an unknown filter field; the [address budget](/streams/filters#the-address-budget) is spent |
| `UNSUPPORTED_CHAIN` | `chain` is not a supported slug |

<RequestExample>
  ```json Subscribe theme={null}
  {
    "action": "subscribe",
    "channel": "wallet.balances",
    "filters": {
      "chain": "solana",
      "wallets": ["7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"]
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```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
    }
  }
  ```
</ResponseExample>


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