wallet.balances

{
  "action": "subscribe",
  "channel": "wallet.balances",
  "filters": {
    "chain": "solana",
    "wallets": ["7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"]
  }
}

{
  "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
  }
}

{
  "action": "subscribe",
  "channel": "wallet.balances",
  "filters": {
    "chain": "solana",
    "wallets": ["7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"]
  }
}

{
  "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
  }
}

Subscribe on an open stream connection. See Connecting to streams for the connection, frames and reconnecting.

Filters

string

required

The chain slug the wallets hold balances on.

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.

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

Subscribe.
Read Wallet balances with the same wallets and chains set to the subscription’s chain.
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 is spent
`UNSUPPORTED_CHAIN`	`chain` is not a supported slug

{
  "action": "subscribe",
  "channel": "wallet.balances",
  "filters": {
    "chain": "solana",
    "wallets": ["7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"]
  }
}

{
  "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
  }
}

REST

Streams

Filters

Update

Snapshot, then stream

Errors

​Filters

​Update

​Snapshot, then stream

​Errors

Filters

Update

Snapshot, then stream

Errors