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

# Balances

> Access realtime token balances. Get comprehensive details about native and ERC20 tokens, including token metadata and USD valuations.

export const SupportedChains = ({endpoint, title, excludeChains}) => {
  const dataState = useState(null);
  const data = dataState[0];
  const setData = dataState[1];
  useEffect(function () {
    var url = "https://api.sim.dune.com/v1/evm/supported-chains";
    fetch(url, {
      method: "GET"
    }).then(function (response) {
      return response.json();
    }).then(function (responseData) {
      setData(responseData);
    });
  }, [endpoint]);
  if (data === null) {
    return <div>Loading chain information...</div>;
  }
  if (!data.chains) {
    return <div>No chain data available</div>;
  }
  var supportedChains = [];
  var totalChains = data.chains.length;
  var excludedChainNames = excludeChains || [];
  for (var i = 0; i < data.chains.length; i++) {
    var chain = data.chains[i];
    if (excludedChainNames.indexOf(chain.name) !== -1) continue;
    if (endpoint === undefined) {
      supportedChains.push(chain);
    } else if (chain[endpoint] && chain[endpoint].supported) {
      supportedChains.push(chain);
    }
  }
  var count = supportedChains.length;
  var endpointName = endpoint ? endpoint.charAt(0).toUpperCase() + endpoint.slice(1).replace(/_/g, " ") : "All";
  var accordionTitle = title ? title + " (" + count + ")" : "Supported Chains (" + count + ")";
  return <Accordion title={accordionTitle}>
      <table>
        <thead>
          <tr>
            <th>name</th>
            <th>chain_id</th>
            <th>tags</th>
          </tr>
        </thead>
        <tbody>
          {supportedChains.map(function (chain) {
    return <tr key={chain.name}>
                <td><code>{chain.name}</code></td>
                <td><code>{chain.chain_id}</code></td>
                <td><code>{chain.tags ? chain.tags.join(", ") : ""}</code></td>
              </tr>;
  })}
        </tbody>
      </table>
    </Accordion>;
};

export const DefaultChainCount = ({endpoint}) => {
  const dataState = useState(null);
  const data = dataState[0];
  const setData = dataState[1];
  useEffect(function () {
    fetch("https://api.sim.dune.com/v1/evm/supported-chains", {
      method: "GET"
    }).then(function (response) {
      return response.json();
    }).then(function (responseData) {
      setData(responseData);
    });
  }, []);
  if (data === null) {
    return <>N</>;
  }
  if (!data.chains || !Array.isArray(data.chains)) {
    return <>N</>;
  }
  var uniqueDefaultChains = new Set();
  for (var i = 0; i < data.chains.length; i++) {
    var chain = data.chains[i];
    var hasDefaultTag = Array.isArray(chain.tags) && chain.tags.indexOf("default") !== -1;
    if (!hasDefaultTag) {
      continue;
    }
    if (endpoint !== undefined) {
      if (chain[endpoint] && chain[endpoint].supported === true) {
        uniqueDefaultChains.add(chain.name);
      }
    } else {
      uniqueDefaultChains.add(chain.name);
    }
  }
  var count = uniqueDefaultChains.size;
  return <>{count}</>;
};

<img src="https://mintcdn.com/sim-dune/ZJaWY5isqbzG1C45/images/balance.svg?fit=max&auto=format&n=ZJaWY5isqbzG1C45&q=85&s=ba4eaa3cbcf7999edd74f2c7db9db8df" alt="Balance Sv" width="720" height="275" data-path="images/balance.svg" />

The Token Balances API provides accurate and fast real time balances of the native and ERC20 tokens of accounts on supported EVM blockchains.

<SupportedChains endpoint="balances" />

<Tip>
  Looking for the balance of a single token for a wallet? See <a href="#single-token-balance">Single token balance</a>.
</Tip>

<Tip>
  Looking for only stablecoin balances? Use the dedicated <a href="/evm/stablecoins">Stablecoins</a> endpoint or add `asset_class=stablecoin` to your request.
</Tip>

## Token Prices

Sim looks up prices onchain. We use the most liquid onchain pair to determine a USD price. We return the available liquidity in `pool_size` as part of the response, and show a warning `low_liquidity:	true` if this value is less than \$10k.

You can include `metadata=pools` in your request to see which liquidity pool was used for pricing each token. The returned `pool` object includes `pool_type`, `address`, `chain_id`, and `tokens`.

## Token Filtering

We also include the `pool_size` field in all responses, allowing you to implement custom filtering logic based on your specific requirements. For a detailed explanation of our approach, see our [Token Filtering](/token-filtering) guide.

### Exclude unpriced balances

By default, balances for tokens without available pricing data are included in responses. To filter them out, pass `exclude_unpriced=true`.

### Exclude tokens with less than 100 USD liquidity

Use the optional `exclude_spam_tokens` query parameter to automatically filter out tokens with less than 100 USD of liquidity. Include the query parameter `exclude_spam_tokens=true` so that those tokens are excluded from the response entirely. This is distinct from the `low_liquidity` field in the response, which is `true` when liquidity is below 10,000. To learn more about how Sim calculates liquidity data, visit the [Token Filtering](/token-filtering) guide.

## Compute Unit Cost

The Balances endpoint’s CU cost equals the number of chains you include via the `chain_ids` query parameter.
For example, `?chain_ids=1,8453,137` processes three chains and consumes three CUs.

<Note>
  If you omit `chain_ids`, the endpoint uses its `default` chain set (low-latency networks), which equals {<DefaultChainCount endpoint="balances" />} chains at request time (subject to change). See the tags section of the <a href="/evm/supported-chains#tags">Supported Chains</a> page and the <a href="/compute-units">Compute Units</a> page for details.
</Note>

## Historical prices

You can request historical point-in-time prices by adding the `historical_prices` query parameter. Use whole numbers to specify the number of hours in the past. You can request up to three offsets. For example, `&historical_prices=168` returns the price 168 hours (1 week) ago. `&historical_prices=720,168,24` returns prices 720 hours (1 month) ago, 168 hours (1 week) ago, and 24 hours ago.

<Note>
  The `historical_prices` parameter is currently supported only on the EVM Balances and EVM Token Info endpoints.
</Note>

When set, each balance includes a `historical_prices` array with one entry per offset:

```json theme={null}
{
  "balances": [
    {
      "symbol": "ETH",
      "price_usd": 3896.8315,
      "historical_prices": [
        { "offset_hours": 8760, "price_usd": 2816.476803 },
        { "offset_hours": 720,  "price_usd": 3710.384068 },
        { "offset_hours": 168,  "price_usd": 3798.632723 }
      ]
    }
  ]
}
```

**Percent changes are not returned**. You can compute your own differences using the `price_usd` on the balance and the values in `historical_prices[].price_usd`.

<Warning>
  The maximum number of historical price offsets is 3. If more than 3 are provided, the API returns an error.
</Warning>

## Warnings

When requesting balances for specific chains using the `chain_ids` parameter, the API may return warnings if some requested chain IDs are not supported. Unlike errors, warnings indicate non-fatal issues where the request can still be partially fulfilled.

When unsupported chain IDs are included in your request, the API will:

* Return balances for all supported chains you requested
* Include a `warnings` array in the response with details about the unsupported chains

### Example: Request with Unsupported Chain IDs

If you request `?chain_ids=1,9999,10,77777777777`, the API returns balances for chains 1 and 10 (supported), and includes a warning about chains 9999 and 77777777777 (unsupported):

```json theme={null}
{
  "wallet_address": "0x37305b1cd40574e4c5ce33f8e8306be057fd7341",
  "balances": [
    {
      "chain": "ethereum",
      "chain_id": 1,
      "address": "native",
      "amount": "1000000000000000000",
      "symbol": "ETH",
      "decimals": 18,
      "price_usd": 3896.8315,
      "value_usd": 3896.8315
    },
    {
      "chain": "optimism",
      "chain_id": 10,
      "address": "native",
      "amount": "500000000000000000",
      "symbol": "ETH",
      "decimals": 18,
      "price_usd": 3896.8315,
      "value_usd": 1948.41575
    }
  ],
  "warnings": [
    {
      "code": "UNSUPPORTED_CHAIN_IDS",
      "message": "Some requested chain_ids are not supported. Balances are returned only for supported chains.",
      "chain_ids": [9999, 77777777777],
      "docs_url": "https://docs.sim.dune.com/evm/supported-chains"
    }
  ]
}
```

<Tip>
  Check the [Supported Chains](/evm/supported-chains) page to see which chains are currently supported for the Balances endpoint.
</Tip>

## Pagination

This endpoint is using cursor based pagination. You can use the `limit` query parameter to define the maximum page size.
Results might at times be less than the maximum page size.
The `next_offset` value is passed back by the initial response and can be used to fetch the next page of results, by passing it as the `offset` query parameter in the next request.

<Warning>
  You can only use the value from `next_offset` to set the `offset` query parameter of the next page of results.
</Warning>

## Single token balance

Use the token sub-path of the Balances endpoint to fetch a wallet’s balance for one token on one chain.

This sub-path accepts exactly one chain via the `chain_ids` query parameter.

<Tabs>
  <Tab title="ERC-20 token">
    Use the ERC-20 contract address in `{token_address}`.

    ```bash theme={null}
    curl -s -X GET 'https://api.sim.dev.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/token/0x146523e8db6337291243a63a5555f446fa6c279f?chain_ids=1' \
      -H 'X-Sim-Api-Key: YOUR_API_KEY'
    ```

    ```json theme={null}
    {
      "request_time": "2025-10-11T03:47:29.364380268+00:00",
      "response_time": "2025-10-11T03:47:29.380032150+00:00",
      "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "balances": [
        {
          "chain": "ethereum",
          "chain_id": 1,
          "address": "0x146523e8db6337291243a63a5555f446fa6c279f",
          "amount": "7156868995423049840501842481",
          "symbol": "AiMeme",
          "name": "Ai Meme",
          "decimals": 18,
          "price_usd": 102826.739324412,
          "value_usd": 735917502571333,
          "pool_size": 9.09741149400001,
          "low_liquidity": true
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Native asset">
    Set `{token_address}` to `native`.

    ```bash theme={null}
    curl -s -X GET 'https://api.sim.dev.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/token/native?chain_ids=1' \
      -H 'X-Sim-Api-Key: YOUR_API_KEY'
    ```

    ```json theme={null}
    {
      "request_time": "2025-10-11T03:48:00.471500727+00:00",
      "response_time": "2025-10-11T03:48:00.485194141+00:00",
      "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "balances": [
        {
          "chain": "ethereum",
          "chain_id": 1,
          "address": "native",
          "amount": "783060447601684229",
          "symbol": "ETH",
          "decimals": 18,
          "price_usd": 3779.154092,
          "value_usd": 2959.30609483726
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### Compute Unit Cost

This sub-path has a fixed CU cost of **1** per request.

## Real-Time Updates

<Tip>
  **Skip the polling.** Use the [Subscriptions API](/evm/subscriptions) to receive webhook notifications the moment balance changes occur. [Set up a webhook in minutes](/evm/subscriptions/create-webhook).
</Tip>


## OpenAPI

````yaml /openapi.json GET /v1/evm/balances/{address}
openapi: 3.0.3
info:
  title: Sim API
  description: >-
    The Sim API by Dune provides real-time blockchain data across EVM and SVM
    chains. Access token balances, transaction history, on-chain activity, DeFi
    positions, NFT collectibles, token information, and webhook subscriptions
    through a unified REST API.
  version: 1.0.0
  license:
    name: ''
  contact:
    name: Dune Support
    url: https://docs.sim.dune.com
    email: support@dune.com
servers:
  - url: https://api.sim.dune.com
security:
  - ApiKeyAuth: []
tags:
  - name: evm
    description: EVM-compatible blockchain endpoints.
  - name: svm
    description: Solana/SVM blockchain endpoints.
  - name: activity
    description: On-chain activity feed.
  - name: balances
    description: Token balances (EVM and SVM).
  - name: transactions
    description: Transaction history (EVM and SVM).
  - name: collectibles
    description: NFT and ERC721/ERC1155 holdings.
  - name: defi
    description: DeFi protocol positions.
  - name: supported-chains
    description: Supported blockchain networks.
  - name: token-info
    description: Token metadata and pricing.
  - name: token-holders
    description: Token holder distribution.
  - name: subscriptions
    description: >-
      Webhook subscription management for real-time on-chain event
      notifications.
paths:
  /v1/evm/balances/{address}:
    get:
      tags:
        - evm
        - balances
      summary: Get EVM token balances for a given address
      description: >-
        This endpoint returns EVM token balances for an address for any token
        that the address has interacted with
      operationId: getEvmBalances
      parameters:
        - name: address
          in: path
          description: Wallet address to get balances for
          required: true
          schema:
            type: string
            format: address
            pattern: ^0x[a-fA-F0-9]{40}$
            default: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
        - name: chain_ids
          in: query
          required: false
          description: >-
            Filter by chain(s). Accepts numeric chain IDs and/or tags. Provide a
            single value (e.g. `?chain_ids=1` or `?chain_ids=mainnet`) or a
            comma-separated list (e.g. `?chain_ids=1,8543,testnet`). Chain names
            are not accepted. If this query parameter is omitted, results
            include balances from chains with the `default` tag. See the
            [Supported Chains Tags](/evm/supported-chains#tags) section.
          schema:
            type: string
        - name: filters
          in: query
          description: >-
            Specify `erc20` or `native` to get only ERC20 tokens or native
            assets, respectively
          required: false
          schema:
            type: string
            enum:
              - erc20
              - native
        - name: asset_class
          in: query
          description: >-
            Filter by asset class. Use `stablecoin` to return only stablecoin
            balances. This is equivalent to using the `/stablecoins` endpoint.
          required: false
          schema:
            type: string
            enum:
              - stablecoin
        - name: metadata
          in: query
          description: >-
            A comma separated list of additional metadata fields to include for
            each token. Supported values: `logo`, `url`, `pools`
          required: false
          schema:
            type: string
        - name: exclude_spam_tokens
          in: query
          description: >-
            When true, excludes tokens with less than 100 USD liquidity from the
            response. This differs from the `low_liquidity` field in the
            response.
          required: false
          schema:
            type: boolean
            default: false
        - name: exclude_unpriced
          in: query
          description: >-
            When true, excludes balances for tokens without available pricing
            data. By default, unpriced token balances are included.
          required: false
          schema:
            type: boolean
            default: false
        - name: historical_prices
          in: query
          description: >-
            Historical price selection. Provide a single integer or a
            comma-separated list of up to 3 integers representing hours in the
            past (e.g. `168` for 1 week ago or `720,168,24` for 1 month, 1 week,
            and 1 day ago). When set, each balance includes a historical_prices
            array with one entry per offset.
          required: false
          schema:
            type: string
          examples:
            single_offset:
              summary: Single offset (1 week ago)
              value: '168'
            three_offsets:
              summary: Three offsets (1 month, 1 week, 1 day ago)
              value: 720,168,24
        - name: offset
          in: query
          description: >-
            The offset to paginate through result sets. This is a cursor being
            passed from the previous response, only use what the backend returns
            here.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: >-
            Maximum number of balances to return. Default is 1000 when not
            provided. Values above 1000 are reduced to 1000.
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 1000
            default: 1000
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
              examples:
                success:
                  value:
                    wallet_address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
                    balances:
                      - chain: ethereum
                        chain_id: 1
                        address: '0x0e36c45d16585d1801e37cfaa577a9ad39f9343a'
                        amount: '45787557175393926414790300082'
                        symbol: Kendu
                        name: Kendu of Bank
                        decimals: 18
                        price_usd: 1.233346836175539e+21
                        value_usd: 5.647193877847869e+31
                        pool_size: 1233.34683617554
                        low_liquidity: true
                      - chain: ethereum
                        chain_id: 1
                        address: '0x113404d2003c4acf4231a3a62374bb503bff03d7'
                        amount: '432599243131405501735524'
                        symbol: ALT
                        name: AltLayer
                        decimals: 18
                        price_usd: 9388386012000030000
                        value_usd: 4.061408683016688e+24
                        pool_size: 9.38838601200001
                        low_liquidity: true
                    next_offset: opaque-pagination-token
                    request_time: '2025-08-13T10:31:08Z'
                    response_time: '2025-08-13T10:31:08Z'
                with_warnings:
                  summary: Response with unsupported chain IDs warning
                  value:
                    wallet_address: '0x37305b1cd40574e4c5ce33f8e8306be057fd7341'
                    balances:
                      - chain: ethereum
                        chain_id: 1
                        address: native
                        amount: '1000000000000000000'
                        symbol: ETH
                        decimals: 18
                        price_usd: 3896.8315
                        value_usd: 3896.8315
                      - chain: optimism
                        chain_id: 10
                        address: native
                        amount: '500000000000000000'
                        symbol: ETH
                        decimals: 18
                        price_usd: 3896.8315
                        value_usd: 1948.41575
                    warnings:
                      - code: UNSUPPORTED_CHAIN_IDS
                        message: >-
                          Some requested chain_ids are not supported. Balances
                          are returned only for supported chains.
                        chain_ids:
                          - 9999
                          - 77777777777
                        docs_url: https://docs.sim.dune.com/evm/supported-chains
                    request_time: '2025-12-16T10:31:08Z'
                    response_time: '2025-12-16T10:31:08Z'
        '400':
          description: Bad Request - Invalid wallet address or invalid query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMessageErrorResponse'
              examples:
                invalidAddress:
                  summary: Invalid address format
                  value:
                    message: Failed to parse address
        '401':
          description: Unauthorized - Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorResponse'
              examples:
                invalidApiKey:
                  value:
                    error: invalid API Key
        '429':
          description: Rate Limit Exceeded - Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorResponse'
              examples:
                rateLimitExceeded:
                  value:
                    error: >-
                      Too many requests. Please contact sales@dune.com to
                      increase your limit.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMessageErrorResponse'
              examples:
                internalError:
                  value:
                    message: Internal server error
        '503':
          description: >-
            Service Unavailable - The balances service is temporarily in a retry
            state. Retry the request after a short delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMessageErrorResponse'
              examples:
                serviceUnavailable:
                  value:
                    message: Try again later
components:
  schemas:
    BalancesResponse:
      type: object
      required:
        - wallet_address
        - balances
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/BalanceData'
        errors:
          allOf:
            - $ref: '#/components/schemas/BalanceErrors'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
          description: >-
            Array of warnings that occurred during request processing. Warnings
            indicate non-fatal issues (e.g., unsupported chain IDs) where the
            request can still be partially fulfilled.
        next_offset:
          type: string
          description: >-
            Use this value as the `offset` in your next request to continue
            pagination. Not included when there are no more balances.
        request_time:
          type: string
          format: date-time
          description: Timestamp of when the request was received.
        response_time:
          type: string
          format: date-time
          description: Timestamp of when the response was generated.
        wallet_address:
          type: string
          example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
    ServiceMessageErrorResponse:
      type: object
      description: Error response from backend services that use a message field.
      properties:
        message:
          type: string
          description: Error message.
      required:
        - message
    GatewayErrorResponse:
      type: object
      description: >-
        Error response from the API gateway. Returned for authentication,
        permissions, rate-limiting, and quota errors.
      properties:
        error:
          type: string
          description: Error message.
      required:
        - error
    BalanceData:
      type: object
      required:
        - chain
        - address
        - amount
      properties:
        address:
          type: string
        amount:
          type: string
        chain:
          type: string
        chain_id:
          type: integer
          format: int64
        decimals:
          type: integer
          format: int64
        low_liquidity:
          type: boolean
        name:
          type: string
        pool_size:
          type: number
          format: double
        price_usd:
          type: number
          format: double
        historical_prices:
          type: array
          items:
            $ref: '#/components/schemas/HistoricalPricePoint'
          description: >-
            Historical price points for the requested offsets. Only present when
            the historical_prices query parameter is provided.
        symbol:
          type: string
        token_metadata:
          type: object
          properties:
            logo:
              type: string
            url:
              type: string
        pool:
          allOf:
            - $ref: '#/components/schemas/PoolMetadata'
          description: >-
            Liquidity pool information used for token pricing. Only present when
            metadata=pools is specified.
        value_usd:
          type: number
          format: double
    BalanceErrors:
      type: object
      properties:
        error_message:
          type: string
        token_errors:
          type: array
          items:
            $ref: '#/components/schemas/BalanceErrorInformation'
    Warning:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Warning code identifier (e.g., 'UNSUPPORTED_CHAIN_IDS')
          example: UNSUPPORTED_CHAIN_IDS
        message:
          type: string
          description: Human-readable warning message
          example: >-
            Some requested chain_ids are not supported. Activity is returned
            only for supported chains.
        chain_ids:
          type: array
          items:
            type: integer
            format: int64
          description: >-
            List of chain IDs that triggered this warning (for chain-related
            warnings)
        docs_url:
          type: string
          description: URL to documentation with more information about the warning
          example: https://docs.sim.dune.com/evm/supported-chains
    HistoricalPricePoint:
      type: object
      required:
        - offset_hours
        - price_usd
      properties:
        offset_hours:
          type: integer
          format: int32
          minimum: 1
        price_usd:
          type: number
          format: double
    PoolMetadata:
      type: object
      required:
        - pool_type
        - address
        - chain_id
        - tokens
      properties:
        pool_type:
          type: string
          description: >-
            The type of liquidity pool used for pricing (e.g., aerodrome_stable,
            uniswap_v2, uniswap_v3)
        address:
          type: string
          description: The contract address of the liquidity pool
        chain_id:
          type: integer
          format: int64
          description: The chain ID where the liquidity pool exists
        tokens:
          type: array
          items:
            type: string
          description: Array of contract addresses for the tokens in the pool
    BalanceErrorInformation:
      type: object
      required:
        - chain_id
        - address
      properties:
        address:
          type: string
        chain_id:
          type: integer
          format: int64
        description:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Sim-Api-Key
      description: >-
        API key for authentication. Obtain your key from the Dune dashboard at
        sim.dune.com.

````