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
  • BASE_MAINNET_FLASHBLOCKS
  • BASE_SEPOLIA_FLASHBLOCKS
  • BSC_MAINNET
  • BSC_TESTNET
  • ETH_MAINNET
  • ETH_SEPOLIA
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

ParameterTypeRequiredDescription
chain_nameenumYesChain name to filter events (e.g. BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
wallet_addressstringYesThe 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

FieldTypeDescription
wallet_addressstringThe wallet address being tracked
chain_namestringThe chain name where the balance is being tracked
last_blockintegerThe latest block number when the balance was updated
itemsarrayArray of token balance items
balancestringRaw token balance (unscaled)
balance_prettyfloatHuman-readable token balance (scaled by decimals)
quote_rate_usdfloatToken exchange rate to USD
quote_usdfloatToken balance in USD
metadataobjectToken contract metadata
is_nativebooleanIf the token is the native token of the chain

​
GraphQL Playground