Token Balances

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

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

GoldRush Streaming API

Resources

Credit Cost

Supported Chains

Parameters

Subscription

Basic Subscription Query

Complete Subscription Query

Response Format

Field Descriptions

GraphQL Playground

Credit Cost

Supported Chains

​Parameters

​Subscription

​Basic Subscription Query

​Complete Subscription Query

​Response Format

​Field Descriptions

​GraphQL Playground

Parameters

Subscription

Basic Subscription Query

Complete Subscription Query

Response Format

Field Descriptions

GraphQL Playground