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.

​
Authentication

Using any of the GoldRush developer tools requires an API key.

Get Started

Sign up for a free API key to get started with GoldRush.

​
Parameters

ParameterTypeRequiredDescription
chain_nameenumYesChain name to filter events (e.g. BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
wallet_addressstringYesThe wallet address to track balances for

​
Connection

If you’re not using the graphql-ws package, you must set the WebSocket protocol header:

"Sec-WebSocket-Protocol" : "graphql-transport-ws"

This header is required for the server to properly recognize and handle your GraphQL subscription requests.

The WebSocket endpoint uses the GraphQL query or subscription protocol. Here are examples of how one can connect with different languages:

import { createClient } from "graphql-ws";

const CONNECTION_URL = "wss://gr-staging.streaming.covalenthq.com/graphql";

const client = createClient({
  url: CONNECTION_URL,
  shouldRetry: (retries) => retries < 5,
  on: {
    connecting: () => {
      console.log("⏳ WebSocket connecting...");
    },
    opened: () => {
      console.log("✅ WebSocket connection established");
    },
    closed: () => {
      console.log("❌ WebSocket connection closed");
    },
    error: (err) => {
      console.error("⚠️ WebSocket error:", err);
    },
  },
});

​
Subscription

Once connected, you can subscribe to the tokenBalancesForWalletAddress endpoint to receive notifications.

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

​
Implementation

client.subscribe({
    query: SUBSCRIPTION_QUERY
}, {
    next: (data) => {
        console.log(JSON.stringify(data));
    },
    error: (err) => console.error("⚠️ Subscription error:", err),
    complete: () => console.log("✅ Subscription completed"),
})

​
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