> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Balances

export const GIQL = ({readOnly, query}) => {
  return <iframe className="w-full h-96" src={`https://goldrush-graphql-playground.vercel.app/?query=${encodeURIComponent(query)}&readOnly=${readOnly}`} title="GraphQL Playground" />;
};

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

<CardGroup cols={2}>
  <Card title="Credit Cost"> TBD </Card>

  <Card title="Supported Chains">
    * `BASE_MAINNET`
    * `BASE_SEPOLIA`
    * `BASE_MAINNET_FLASHBLOCKS`
    * `BASE_SEPOLIA_FLASHBLOCKS`
    * `BSC_MAINNET`
    * `BSC_TESTNET`
    * `ETH_MAINNET`
    * `ETH_SEPOLIA`
  </Card>
</CardGroup>

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

  We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features.
</Note>

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

```graphql theme={null}
subscription {
  tokenBalancesForWalletAddress(
    chain_name: BASE_MAINNET,
    wallet_address: "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc"
  ) {
    wallet_address
    chain_name
    last_block
    items {
      balance
      balance_pretty
      quote_usd
    }
  }
}
```

### Complete Subscription Query

```graphql theme={null}
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:

```json theme={null}
{
  "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

<GIQL
  readOnly={false}
  query={`subscription {
  tokenBalancesForWalletAddress(
    chain_name: BASE_MAINNET
    wallet_address: "0x4200000000000000000000000000000000000011"
  ) {
    wallet_address
    chain_name
    last_block
    items {
      balance
      balance_pretty
      quote_usd
      is_native
      metadata {
        contract_name
        contract_ticker_symbol
        contract_address
        contract_decimals
      }
    }
  }
}`}
/>