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

# Stablecoin Balances Enriched (EVM)

> Daily stablecoin balances with address-type enrichment across 37 supported EVM chains

export const StablecoinBalancesSupplyNote = ({filterHint, includeCoverageGap = false, includeAddressCategoryBridge = false}) => <>
    <h2>Interpreting balances vs circulating supply</h2>
    <ul>
      <li>This table represents onchain balances, which is different from circulating supply.</li>
      <li>Bridge-locked funds are intentionally included in balances. For example, more than $4B USDT can appear in the Tether <code>USDT0Adapter</code> contract on Ethereum while representing circulating <code>USDT0</code> on other chains.</li>
      <li>We are not subtracting bridge balances at this stage because exclusions are not objective across bridge designs, and some bridge-held balances represent liquidity for chains not covered elsewhere.</li>
      {includeCoverageGap && <li>Excluding only selected bridges would also be incomplete in practice: some bridge-held balances represent liquidity for chains not covered elsewhere (for example Lighter and Hyperliquid bridge balances).</li>}
      {includeAddressCategoryBridge && <li>Bridge exposure is directly analyzable with <code>address_category = 'bridge'</code>.</li>}
      <li>{filterHint}</li>
      <li>We will continue to work toward a more reliable total supply measure.</li>
    </ul>
  </>;

export const PremiumDatasetAccessCard = ({href = "https://dune.com/enterprise#contact-form"}) => <Card title="Premium dataset access" icon="info" href={href}>
    This dataset is part of a premium offering and requires additional access. Contact the Dune enterprise team to request access.
  </Card>;

The `stablecoins_evm.balances_enriched` table extends EVM stablecoin balances with address classification, entity tags, and whale flags.

<PremiumDatasetAccessCard />

## Why these enriched tables matter

Stablecoin analysis comes down to two fundamental questions:

1. Where are stablecoins right now? (balances)
2. How did they get there? (activity)

This balances-enriched table answers the first question by going beyond raw balances and adding attribution for where capital sits: CEX, lending, treasury, yield, bridge, whale concentration, and more.

## Table schema

| Column                | Type        | Description                                       |
| --------------------- | ----------- | ------------------------------------------------- |
| `blockchain`          | `VARCHAR`   | Chain name                                        |
| `day`                 | `DATE`      | Balance date (partition column)                   |
| `address`             | `VARBINARY` | Holder address                                    |
| `token_symbol`        | `VARCHAR`   | Token symbol                                      |
| `token_address`       | `VARBINARY` | Token contract address                            |
| `token_standard`      | `VARCHAR`   | Token standard (`erc20`)                          |
| `token_id`            | `VARCHAR`   | Always `NULL`                                     |
| `balance_raw`         | `UINT256`   | Raw balance                                       |
| `balance`             | `DOUBLE`    | Decimals-adjusted balance                         |
| `balance_usd`         | `DOUBLE`    | USD value                                         |
| `currency`            | `VARCHAR`   | ISO 4217 code                                     |
| `address_category`    | `VARCHAR`   | Address category (see below)                      |
| `address_subcategory` | `VARCHAR`   | Address subcategory                               |
| `address_project`     | `VARCHAR`   | Project/entity name (nullable)                    |
| `address_version`     | `VARCHAR`   | Project version (nullable)                        |
| `address_label`       | `VARCHAR`   | Label value (nullable)                            |
| `is_smart_contract`   | `BOOLEAN`   | Contract flag                                     |
| `is_whale`            | `BOOLEAN`   | Address holds >= \$10M total stablecoins that day |
| `last_updated`        | `TIMESTAMP` | Last balance update time                          |

## Address categories

Every address receives exactly one `address_category` — no double counting is possible by construction. When an address matches a curated label, that label wins. Unlabeled addresses fall through: smart contract → `unidentified_smart_contract`, EOA with >= \$10M → `unidentified_whale`, otherwise → `unidentified`.

When an address appears in multiple label sets, a fixed priority order resolves the conflict (table is ordered by priority, highest first):

| `address_category`            | Allowed `address_subcategory` values           | Description                                                                            |
| ----------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| `erc20_contract`              | `erc20_contract`                               | Canonical stablecoin token contracts defining supply. Not deployed capital.            |
| `dex`                         | `dex_liquidity`, `dex_execution`               | Stablecoins in decentralized exchange pools and routing contracts.                     |
| `lending`                     | `lending_liquidity`, `lending_execution`       | Stablecoins deployed as credit in lending protocols.                                   |
| `bridge`                      | `bridge_liquidity`                             | Stablecoins escrowed or locked for cross-chain transfers.                              |
| `yield`                       | `yield_liquidity`, `yield_execution`           | Stablecoins in strategy or wrapper contracts earning passive yield.                    |
| `issuer`                      | `issuer_operations`, `issuer_treasury`         | Stablecoin monetary infrastructure — minting, redemption, peg management.              |
| `treasury_or_governance`      | `treasury`, `treasury_collector`, `governance` | Protocol-controlled capital for governance, reserves, or fees.                         |
| `cex`                         | `cex`                                          | Known exchange-controlled wallets (hot and cold). Not user deposit addresses.          |
| `burn`                        | `burn`                                         | Irrecoverable token sinks (dead/burn addresses).                                       |
| `unidentified_smart_contract` | `unidentified_smart_contract`                  | Contracts detected onchain but not yet categorized.                                    |
| `unidentified_whale`          | `unidentified_whale`                           | Unlabeled EOAs holding >= \$10M total stablecoin balance that day. Recalculated daily. |
| `unidentified`                | `unidentified`                                 | Addresses with no known classification.                                                |

As label coverage expands, new values may be added in backward-compatible fashion.

## Methodology

1. Start from daily rows in `stablecoins_evm.balances`.
2. Join curated address labels to assign `address_category`, subcategory, and project metadata where a label exists.
3. Derive `is_smart_contract` (from creation traces) and `is_whale` (>= \$10M total stablecoin balance) flags per address per day.
4. Apply the priority waterfall for unlabeled addresses to maintain complete coverage.

Category totals should be interpreted as "where balances sit" rather than ownership or liability accounting. Labels represent the best-known economic function of an address and can evolve as coverage improves.

## Sample query

```sql theme={null}
SELECT
    b.address_category
    , b.token_symbol
    , SUM(b.balance_usd) AS total_usd
FROM stablecoins_evm.balances_enriched AS b
WHERE b.blockchain = 'ethereum'
    AND b.day = CURRENT_DATE
    AND b.balance > 0
GROUP BY b.address_category, b.token_symbol
ORDER BY total_usd DESC
```

## Notes

* For performance, filter by `blockchain` and `day`.
* Bridge balances are intentionally retained. Filter with `address_category = 'bridge'` to exclude them.

<StablecoinBalancesSupplyNote includeAddressCategoryBridge={true} filterHint={<>If you want a circulating-supply-style view, filter out rows where <code>address_category = 'bridge'</code>.</>} />