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

# Token Balances by Wallet Address

> To query the token balances of a wallet address across networks

export const CacheInfo = ({publicRate, paidRate, rate}) => {
  const fmt = v => v === 0 ? 'Real-time (Cacheless)' : `Every ${v}`;
  if (rate !== undefined) {
    return <Callout icon="clock-rotate-left" color="#2196F3" iconType="regular">
        <strong>Cache / Update Frequency:</strong><br />{fmt(rate)}
      </Callout>;
  }
  if (publicRate !== undefined && paidRate !== undefined) {
    return <Callout icon="clock-rotate-left" color="#2196F3" iconType="regular">
        <strong>Cache / Update Frequency:</strong><ul><li>{fmt(paidRate)} (Paid API)</li><li>{fmt(publicRate)} (Demo / Keyless API)</li></ul>
      </Callout>;
  }
  return null;
};

export const PlanExclusivity = ({tier}) => {
  if (tier === "enterprise") {
    return <Callout icon="crown" color="#FFC107" iconType="regular">
        <strong>Enterprise Only</strong><br />This endpoint is exclusively available to <strong>Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/enterprise">→ Contact sales</a>
      </Callout>;
  }
  if (tier === "analyst_above") {
    return <Callout icon="briefcase" color="#FFC107" iconType="regular">
        <strong>Analyst Plan and Above</strong><br />This endpoint is only available to <strong>Analyst, Lite, Pro, and Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/pricing">→ View pricing</a>
      </Callout>;
  }
  if (tier === "basic_above") {
    return <Callout icon="briefcase" color="#FFC107" iconType="regular">
        <strong>Basic Plan and Above</strong><br />This endpoint is only available to <strong>Basic, Analyst, Lite, Pro, and Enterprise</strong> plan.<br /><a href="https://www.coingecko.com/en/api/pricing">→ View pricing</a>
      </Callout>;
  }
  throw new Error(`PlanExclusivity: invalid tier "${tier}". Use "basic_above", "analyst_above", or "enterprise".`);
};

#### Notes

* `total_value_usd` and `total_holdings` are scoped to the request, not to the wallet's whole portfolio:
  * Only the networks named in `networks` are counted.
  * `token_type`, `value_usd_min` and `reserve_in_usd_min` filters are applied first.
* `price_usd` and `value_usd` come back `null` rather than omitted when a token has no price.
* `balance` is full precision and never rounded, but comes back `null` when the token cannot be resolved. `balance_raw` is always present, so fall back to it and convert with `decimals`: `balance_raw / 10^decimals`.
* Filtering by `token_type` returns these `balances.token_type` values:

  | `token_type` param | `balances.token_type` field |
  | ------------------ | --------------------------- |
  | `native`           | `native`                    |
  | `non_native`       | `erc20`, `spl`              |
  | omitted            | all of the above            |

<Accordion title="Supported networks">
  | Chain     | Network `id`  |
  | --------- | ------------- |
  | Ethereum  | `eth`         |
  | Base      | `base`        |
  | BNB Chain | `bsc`         |
  | Polygon   | `polygon_pos` |
  | Arbitrum  | `arbitrum`    |
  | Optimism  | `optimism`    |
  | Avalanche | `avax`        |
  | Stable    | `stable`      |
  | Robinhood | `robinhood`   |
</Accordion>

<Warning>
  Every network in one request must belong to the same VM family, or the request returns a `400`.

  * For example, `networks=eth,base,arbitrum` is valid because all three are EVM.
  * Networks from different VM families must be queried in separate calls.
</Warning>

<PlanExclusivity tier="analyst_above" />

<CacheInfo rate="10 seconds" />


## OpenAPI

````yaml openapi-specs/pro-api.json get /onchain/wallets/{address}/balances
openapi: 3.0.0
info:
  title: CoinGecko Pro API
  version: 3.0.0
servers:
  - url: https://pro-api.coingecko.com/api/v3
security:
  - headerAuth: []
  - queryAuth: []
paths:
  /onchain/wallets/{address}/balances:
    get:
      summary: Token Balances by Wallet Address
      description: To query the token balances of a wallet address across networks
      operationId: wallet-token-balances
      parameters:
        - name: address
          in: path
          required: true
          description: Wallet address.
          schema:
            type: string
            default: '0x9642b23ed1e01df1092b92641051881a322f5d4e'
        - name: networks
          in: query
          required: true
          description: >-
            Query balances by networks, comma-separated if more than one. 

            *refers to [supported
            networks](/reference/wallet-token-balances#supported-networks).
          schema:
            type: string
            default: eth,base
        - name: sort
          in: query
          required: false
          description: |-
            Sort the holdings by field. 
            Default: `value_usd_desc`
          schema:
            type: string
            enum:
              - value_usd_desc
              - value_usd_asc
        - name: token_type
          in: query
          required: false
          description: |-
            Filter holdings by token type. 
            Omit to return both.
          schema:
            type: string
            enum:
              - native
              - non_native
        - name: value_usd_min
          in: query
          required: false
          description: Minimum holding value in USD.
          schema:
            type: number
        - name: reserve_in_usd_min
          in: query
          required: false
          description: Minimum total reserve in USD of the holding's token.
          schema:
            type: number
        - name: page
          in: query
          required: false
          description: |-
            Page through results. 
            Default value: 1
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: |-
            Total results per page. 
            Default value: 50 
            Valid values: 1...100
          schema:
            type: integer
      responses:
        '200':
          description: Wallet token balances data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTokenBalances'
              example:
                data:
                  id: '0x9642b23ed1e01df1092b92641051881a322f5d4e'
                  type: wallet_balance
                  attributes:
                    wallet_address: '0x9642b23ed1e01df1092b92641051881a322f5d4e'
                    total_value_usd: '91333695.8924553249294795652'
                    total_holdings: 3235
                    networks:
                      - network: eth
                        value_usd: '91333647.2139247191042473531'
                        holdings: 2784
                        last_updated_at: '2026-09-09T04:53:53Z'
                      - network: base
                        value_usd: '48.6785306058252322121'
                        holdings: 451
                        last_updated_at: '2026-09-09T04:54:00Z'
                    balances:
                      - network: eth
                        address: '0xae7ab96520de3a18e5e111b5eaab095312d7fe84'
                        token_type: erc20
                        name: Liquid staked Ether 2.0
                        symbol: stETH
                        decimals: 18
                        coingecko_coin_id: staked-ether
                        balance_raw: '1285426654835126578249'
                        balance: '1285.426654835126578249'
                        price_usd: '2505.0197550041'
                        value_usd: '3220019.16397083'
                        h24_price_change_percentage: '1.1092026358'
                        total_reserve_in_usd: '76309888.5752643'
                      - network: base
                        address: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
                        token_type: native
                        name: Ether
                        symbol: ETH
                        decimals: 18
                        coingecko_coin_id: ethereum
                        balance_raw: '5689474631933105'
                        balance: '0.005689474631933105'
                        price_usd: '2509.94'
                        value_usd: '14.2802399576741775637'
                        h24_price_change_percentage: '1.1788611331'
                        total_reserve_in_usd: >-
                          278512639.26086519127010524563602976339460900489983579581997256928854127324623998556078866976287286661445830154567340658840423188339231363233349708668987943412959855507040548920851997937663037191656718770585834579091087234485520736930186246070127797108954047881409466115545016797903075072
components:
  schemas:
    WalletTokenBalances:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - id
            - type
            - attributes
          properties:
            id:
              type: string
              description: Wallet address
            type:
              type: string
              description: Response type
            attributes:
              type: object
              required:
                - wallet_address
                - total_value_usd
                - total_holdings
                - networks
                - balances
              properties:
                wallet_address:
                  type: string
                  description: Wallet address queried
                total_value_usd:
                  type: string
                  description: >-
                    Total value of matching holdings in USD, across the
                    requested networks only
                total_holdings:
                  type: integer
                  description: >-
                    Number of matching holdings across the requested networks
                    only
                networks:
                  type: array
                  description: >-
                    Value and holding count per network, listing only networks
                    holding a matching balance
                  items:
                    type: object
                    required:
                      - network
                      - value_usd
                      - holdings
                      - last_updated_at
                    properties:
                      network:
                        type: string
                        description: Network ID
                      value_usd:
                        type: string
                        description: >-
                          Total value of matching holdings on this network in
                          USD
                      holdings:
                        type: integer
                        description: Number of matching holdings on this network
                      last_updated_at:
                        type: string
                        format: date-time
                        description: Last updated timestamp
                balances:
                  type: array
                  description: Token holdings, one entry per token
                  items:
                    type: object
                    required:
                      - network
                      - address
                      - token_type
                      - name
                      - symbol
                      - decimals
                      - coingecko_coin_id
                      - balance_raw
                      - balance
                      - price_usd
                      - value_usd
                      - h24_price_change_percentage
                      - total_reserve_in_usd
                    properties:
                      network:
                        type: string
                        description: Network ID
                      address:
                        type: string
                        description: Token contract address
                      token_type:
                        type: string
                        description: Token type, such as native, erc20 or spl
                      name:
                        type: string
                        description: Token name
                      symbol:
                        type: string
                        description: Token symbol
                      decimals:
                        type: integer
                        description: Token decimals
                      coingecko_coin_id:
                        type: string
                        nullable: true
                        description: CoinGecko coin ID
                      balance_raw:
                        type: string
                        description: >-
                          Token balance in the smallest unit, before decimals
                          are applied
                      balance:
                        type: string
                        nullable: true
                        description: Token balance at full precision
                      price_usd:
                        type: string
                        nullable: true
                        description: Token price in USD
                      value_usd:
                        type: string
                        nullable: true
                        description: Value of the holding in USD
                      h24_price_change_percentage:
                        type: string
                        nullable: true
                        description: 24hr price change percentage
                      total_reserve_in_usd:
                        type: string
                        nullable: true
                        description: Total reserve in USD across all pools of the token
  securitySchemes:
    headerAuth:
      type: apiKey
      in: header
      name: x-cg-pro-api-key
      description: >-
        Learn how to [set up your API
        key](https://docs.coingecko.com/docs/setting-up-your-api-key)
    queryAuth:
      type: apiKey
      in: query
      name: x_cg_pro_api_key
      description: >-
        Learn how to [set up your API
        key](https://docs.coingecko.com/docs/setting-up-your-api-key)

````