Token Balances Stream

The Token Balances Stream provides real-time updates on wallet token balances. This documentation follows our standard streaming API structure.

Credit Cost

TBD

Supported Chains

• Base Mainnet
• Base Sepolia Flashblocks
• BSC Mainnet
• BSC Testnet
• Ethereum Mainnet
• Ethereum Sepolia Testnet

This stream is currently in Beta. It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. No API credits are currently charged.

We welcome your feedback so please reach out to us directly to report issues or request features.

Parameters

Parameter	Type	Required	Description
chain_name	enum	Yes	Chain name to filter events (e.g. BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
wallet_address	string	Yes	The wallet address to track balances for

Subscription

You can subscribe to the tokenBalancesForWalletAddress endpoint to receive events.

Basic Subscription Query

subscription {
  tokenBalancesForWalletAddress(
    chain_name: BASE_MAINNET,
    wallet_address: "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc"
  ) {
    wallet_address
    chain_name
    last_block
    items {
      balance
      balance_pretty
      quote_usd
    }
  }
}

Complete Subscription Query

subscription {
  tokenBalancesForWalletAddress(
    chain_name: BASE_MAINNET,
    wallet_address: "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc"
  ) {
    wallet_address
    chain_name
    last_block
    items {
      balance
      balance_pretty
      quote_rate_usd
      quote_usd
      metadata {
        contract_name
        contract_address
        contract_decimals
        contract_ticker_symbol
      }
      is_native
    }
  }
}

Response Format

The subscription returns real-time updates of token balances in the following format:

{
  "data": {
    "tokenBalancesForWalletAddress": {
      "wallet_address": "0x4200000000000000000000000000000000000011",
      "chain_name": "BASE_MAINNET",
      "last_block": 26090254,
      "items": [
        {
          "balance": "650677223795882974342",
          "balance_pretty": 650.6772,
          "quote_rate_usd": "2587.4096",
          "quote_usd": "1683568.4252",
          "metadata": {
            "contract_name": "Ether",
            "contract_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
            "contract_decimals": 18,
            "contract_ticker_symbol": "ETH"
          },
          "is_native": true
        }
      ]
    }
  }
}

Field Descriptions

Field	Type	Description
wallet_address	string	The wallet address being tracked
chain_name	string	The chain name where the balance is being tracked
last_block	integer	The latest block number when the balance was updated
items	array	Array of token balance items
balance	string	Raw token balance (unscaled)
balance_pretty	float	Human-readable token balance (scaled by decimals)
quote_rate_usd	float	Token exchange rate to USD
quote_usd	float	Token balance in USD
metadata	object	Token contract metadata
is_native	boolean	If the token is the native token of the chain

GraphQL Playground