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

# EVM Balance Updates

> Per-block balance changes for fungible tokens on EVM networks.

`balances_<chain>.updates` records one row per observed balance change for native currencies and ERC20 tokens. Each row is the on-chain balance at a specific block for an `(address, token_address)` pair. Refreshed hourly.

For most historical analysis prefer [`balances_<chain>.daily_updates`](/data-catalog/curated/balances/evm-daily-updates), which is faster and includes USD values. Use `balances_<chain>.updates` when you need block-level resolution.

## Table Schema

| Column           | Type        | Description                                                                                                                                       |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blockchain`     | `varchar`   | Chain identifier (e.g. `ethereum`)                                                                                                                |
| `block_date`     | `date`      | Date of `block_number` (partition key)                                                                                                            |
| `block_number`   | `bigint`    | Block at which the balance was observed                                                                                                           |
| `timestamp`      | `timestamp` | Block time                                                                                                                                        |
| `address`        | `varbinary` | Account address                                                                                                                                   |
| `token_address`  | `varbinary` | Token contract address. Native tokens use the standardized address from `dune.blockchains` (zero address on most EVMs, `0x0000…1010` on Polygon). |
| `token_standard` | `varchar`   | `native` or `erc20`                                                                                                                               |
| `token_symbol`   | `varchar`   | Token symbol (nullable)                                                                                                                           |
| `balance_raw`    | `uint256`   | Balance in raw units (smallest denomination)                                                                                                      |
| `balance`        | `double`    | Balance in display units (`balance_raw / 10^decimals`, 18 if unknown)                                                                             |

## Usage Notes

`balances_<chain>.updates` is partitioned by `block_date`. For best performance, include `block_date` and at least one of `address` or `token_address` in your WHERE clause.

### USD Values

This table is intentionally not enriched with USD prices. A balance change observed at a specific block can be priced against many different reference points (time of change, end of day, latest, custom benchmark) and there is no single right choice. Bring your own price by joining `prices.minute`, `prices.hour`, `prices.day`, or `prices.latest` at the time anchor that fits your analysis.

If you only need end-of-day USD values, use [`balances_<chain>.daily_updates`](/data-catalog/curated/balances/evm-daily-updates) where `balance_usd` is precomputed from `prices.day`.

## Example Queries

**All balance updates for a wallet in the last 7 days:**

```sql theme={null}
SELECT block_number, timestamp, token_symbol, balance
FROM balances_ethereum.updates
WHERE block_date >= CURRENT_DATE - INTERVAL '7' day
  AND address = 0xd8da6bf26964af9d7eed9e03e53415d37aa96045
ORDER BY block_number DESC
```

**Mark-to-market a wallet's ETH balance at each change:**

For a volatile asset, attaching the price at the hour of each balance change shows the wallet's USD position as both balances and prices move.

```sql theme={null}
SELECT
    u.block_number,
    u.timestamp,
    u.balance        AS eth_balance,
    u.balance * p.price AS eth_balance_usd
FROM balances_ethereum.updates u
LEFT JOIN prices.hour p
    ON p.blockchain       = 'ethereum'
   AND p.contract_address = u.token_address
   AND p.timestamp        = date_trunc('hour', u.timestamp)
WHERE u.block_date >= DATE '2025-01-01'
  AND u.address       = 0xd8da6bf26964af9d7eed9e03e53415d37aa96045
  AND u.token_address = 0x0000000000000000000000000000000000000000 -- native ETH
ORDER BY u.block_number
```