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

# Stablecoins

> Get realtime stablecoin balances across all supported EVM chains. Includes USD-pegged, yield-bearing, and euro-pegged stablecoins.

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}</>;
};

The Stablecoin Balances API provides a dedicated endpoint for retrieving only stablecoin holdings for a wallet across supported EVM chains. This is a specialized version of the [Balances](/evm/balances) endpoint that filters results to include only configured stablecoins.

<SupportedChains endpoint="balances" />

## Supported Stablecoins

The endpoint includes stablecoins from three categories:

| Category          | Description                   | Examples              |
| ----------------- | ----------------------------- | --------------------- |
| **Standard**      | USD-pegged stablecoins        | USDC, USDT, DAI, BUSD |
| **Yield-bearing** | Stablecoins that accrue yield | sDAI, sUSDe           |
| **Euro-pegged**   | EUR-pegged stablecoins        | EURC, EURe            |

<Info>
  The stablecoin category is used for filtering only and is not included in the response. The response format is identical to the standard Balances endpoint.
</Info>

<Note>
  On Gnosis chain (chain\_id: 100), the native token xDAI is a stablecoin and will be included in results with `address: "native"`.
</Note>

## Alternative Access

You can also access stablecoin balances through the main [Balances](/evm/balances) endpoint using the `asset_class` query parameter:

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

Both methods return identical results.

## Compute Unit Cost

The Stablecoin Balances endpoint's CU cost equals the number of chains you include via the `chain_ids` query parameter, the same as the standard Balances endpoint.

<Note>
  If you omit `chain_ids`, the endpoint uses its `default` chain set, which equals {<DefaultChainCount endpoint="balances" />} chains at request time. See the tags section of the <a href="/evm/supported-chains#tags">Supported Chains</a> page.
</Note>

## Pagination

This endpoint uses cursor-based pagination, identical to the Balances endpoint. Use the `limit` query parameter to define the maximum page size. The `next_offset` value from the response can be used to fetch subsequent pages.

```bash theme={null}
# First page
curl -s -X GET 'https://api.sim.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/stablecoins?limit=10' \
  -H 'X-Sim-Api-Key: YOUR_API_KEY'

# Next page (using next_offset from previous response)
curl -s -X GET 'https://api.sim.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/stablecoins?limit=10&offset=NEXT_OFFSET_VALUE' \
  -H 'X-Sim-Api-Key: YOUR_API_KEY'
```

## Example Response

```json theme={null}
{
  "request_time": "2026-02-05T10:31:08Z",
  "response_time": "2026-02-05T10:31:08Z",
  "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "balances": [
    {
      "chain": "ethereum",
      "chain_id": 1,
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "1000000000",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "price_usd": 1.0,
      "value_usd": 1000.0
    },
    {
      "chain": "gnosis",
      "chain_id": 100,
      "address": "native",
      "amount": "100000000000000000000",
      "symbol": "XDAI",
      "decimals": 18,
      "price_usd": 1.0,
      "value_usd": 100.0
    }
  ]
}
```


## OpenAPI

````yaml /openapi.json GET /v1/evm/balances/{address}/stablecoins
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}/stablecoins:
    get:
      tags:
        - evm
        - balances
      summary: Get stablecoin balances for a given address
      description: >-
        This endpoint returns stablecoin balances for an address across
        supported EVM chains. It filters the standard balances response to
        include only configured stablecoins (USD-pegged, yield-bearing, and
        euro-pegged).
      operationId: getEvmStablecoinBalances
      parameters:
        - name: address
          in: path
          description: Wallet address to get stablecoin 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,8453,137`). If 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 stablecoins or native
            stablecoins (e.g., xDAI on Gnosis), respectively
          required: false
          schema:
            type: string
            enum:
              - erc20
              - native
        - 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/StablecoinBalancesResponse'
              examples:
                success:
                  value:
                    wallet_address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
                    balances:
                      - chain: ethereum
                        chain_id: 1
                        address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
                        amount: '1000000000'
                        symbol: USDC
                        name: USD Coin
                        decimals: 6
                        price_usd: 1
                        value_usd: 1000
                      - chain: base
                        chain_id: 8453
                        address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                        amount: '500000000'
                        symbol: USDC
                        name: USD Coin
                        decimals: 6
                        price_usd: 1
                        value_usd: 500
                      - chain: gnosis
                        chain_id: 100
                        address: native
                        amount: '100000000000000000000'
                        symbol: XDAI
                        decimals: 18
                        price_usd: 1
                        value_usd: 100
                    next_offset: opaque-pagination-token
                    request_time: '2026-02-05T10:31:08Z'
                    response_time: '2026-02-05T10: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:
    StablecoinBalancesResponse:
      type: object
      required:
        - wallet_address
        - balances
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/StablecoinBalanceData'
        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
    StablecoinBalanceData:
      type: object
      required:
        - chain
        - address
        - amount
      properties:
        address:
          type: string
          description: >-
            Token contract address, or 'native' for native stablecoins like xDAI
            on Gnosis
        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.

````