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

# Balances

> Fetch historical and latest balances of wallet assets across time.

## Overview

Our balances models are broadly classified the following:

| Type | Model Name | Description |
| - | - | - |
| Daily | `<chain>.assets.fungible_balances_daily` | Daily balance entry of address & tokens pairs balances. |
| Latest | `<chain>.assets.fungible_balances_latest` | Latest balances of every address & tokens pairs balances. |
| Granular | `<chain>.assets.fungible_balances`/`balances` | Granular block/transaction-level changes in the balances of assets & tokens pairs across wallets. |

## Blockchain Coverage

We support balances data for the following blockchains:

| Blockchain | Balances Model | |
| - | - | - |
| Bitcoin | The `bitcoin.assets.balances` contains Bitcoin balance-block changes in balances. Refer to [here](/historical-data/supported-blockchains/bitcoin-ecosystem/bitcoin/assets/balances#balances) for more details. | |
| Solana | The `solana.assets.balances` contains Solana SOL and SPL token balances models. Refer to [here](/historical-data/supported-blockchains/solana/solana/assets/balances) for more details. | |
| Sui | The `sui.raw.balance_changes`Balance changes track the alterations in the amount of assets held by accounts, caused by transactions on Sui. Refer to [here](/historical-data/supported-blockchains/move-ecosystem/sui/raw/balance-changes#balance-changes) for more details. | |
| Tron | The `tron.assets.fungible_balances` contains TRX and TRC20 token balances models. Refer to [here](/historical-data/supported-blockchains/evm/tron/assets/fungible-balances) for more details. | |
| EVM-Compatible Blockchains | The `crosschain.assets.fungible_balances_evm` model offers a historical record of fungible asset balances, including native gas tokens and ERC-20 compatible tokens. | |

### EVM-Compatible Blockchains

We currently support fungible balances for the following evm-compatible blockchains:

| Blockchain | Network |
| - | - |
| arbitrum | Mainnet |
| avalanche | Mainnet |
| b3 | Mainnet |
| base | Mainnet |
| berachain | Mainnet |
| blast | Mainnet |
| bsc | Mainnet |
| core | Mainnet |
| ethereum | Mainnet |
| hyperevm | Mainnet |
| ink | Mainnet |
| linea | Mainnet |
| optimism | Mainnet |
| plasma | Mainnet |
| polygon | Mainnet |
| scroll | Mainnet |
| soneium | Mainnet |
| unichain | Mainnet |
| vana | Mainnet |
| worldchain | Mainnet |
| x\_layer | Mainnet |
| monad\_testnet | Testnet |

## Daily Balances

Use Cases:

* Track the portfolio balance of wallet over time
* Track the number of holders of an asset over time
* Identify the distribution of assets across wallets over time

### Sample Query: Number of USDC Holders holding >100 USDC daily

```sql theme={null}
select
  date,
  count(distinct case when balance > 0 then  address else null end) as total_holders_count,
  count(distinct case when balance > 100 then  address else null end) as holder_100_usdc_count,
from ethereum.assets.fungible_balances_daily
where token_address = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' -- USDC Token Address
group by all
```

### Sample Query: Portfolio balance of a wallet over time

```sql theme={null}
select
  date,
  count(token_address) as tokens,
  sum(case when token_address = '0x0000000000000000000000000000000000000000' then usd_balance else null end) as native_balance_usd,
  sum(usd_balance) as total_balance_usd
from ethereum.assets.fungible_balances_daily
where address in ('0xe649a394fb16b58ee2e59feb2ea571e7733c812a')
group by all
```

## Latest Balances

Use Cases:

* Track the latest balance of a group of addresses across different blockchains
* Track the distribution of a particular token address currently

### Sample Query: Portfolio balance of a wallet currently

```sql theme={null}
select
  count(token_address) as tokens,
  sum(case when token_address = '0x0000000000000000000000000000000000000000' then usd_balance_current else null end) as native_balance_usd,
  sum(usd_balance_current) as total_balance_usd
from ethereum.assets.fungible_balances_latest
where address in ('0xe649a394fb16b58ee2e59feb2ea571e7733c812a')
group by all
```

## Balances at Any Timestamp

The `sql_table_<chain>_get_balances_at_timestamp` function calculates precise token balances for any list of addresses at a specific point in time. It combines the daily balance snapshot with intraday transaction changes using a **Base + Delta** approach:

**Final Balance = EOD Snapshot + Sum(Credits - Debits since snapshot)**

This is useful when daily snapshots are not granular enough and you need balances at a specific hour or minute.

### Usage

```sql theme={null}
SELECT * FROM TABLE(<chain>.UDFS.SQL_TABLE_<CHAIN>_GET_BALANCES_AT_TIMESTAMP(
    ARRAY_CONSTRUCT('0xAddress1', '0xAddress2'),
    '2025-06-15 14:30:00'::TIMESTAMP_NTZ
));
```

### Example: Portfolio balance at a specific time

```sql theme={null}
SELECT
  address,
  token_symbol,
  balance,
  usd_balance,
  calculation_method
FROM TABLE(ETHEREUM.UDFS.SQL_TABLE_ETHEREUM_GET_BALANCES_AT_TIMESTAMP(
    ARRAY_CONSTRUCT('0xe649a394fb16b58ee2e59feb2ea571e7733c812a'),
    '2025-06-15 14:30:00'::TIMESTAMP_NTZ
))
WHERE balance > 0
ORDER BY usd_balance DESC NULLS LAST;
```

### Return Columns

| Column | Type | Description |
| - | - | - |
| `address` | VARCHAR | Wallet address |
| `token_address` | VARCHAR | Token contract address |
| `token_name` | VARCHAR | Token name |
| `token_symbol` | VARCHAR | Token symbol |
| `token_decimals` | NUMBER | Token decimal places |
| `raw_balance_str` | VARCHAR | Raw balance as string (precision-safe) |
| `raw_balance` | FLOAT | Raw balance as float |
| `balance_str` | VARCHAR | Decimal-adjusted balance as string |
| `balance` | FLOAT | Decimal-adjusted balance |
| `usd_exchange_rate` | FLOAT | USD price at snapshot time |
| `usd_balance` | FLOAT | Balance in USD |
| `last_activity_block_timestamp` | TIMESTAMP\_NTZ | Timestamp of last activity |
| `last_activity_block_number` | NUMBER | Block number of last activity |
| `base_date` | DATE | Date of the EOD snapshot used |
| `intraday_adjustments_applied` | BOOLEAN | Whether intraday deltas were applied |
| `calculation_method` | VARCHAR | `eod_only` or `eod_with_intraday_adjustment` |

### Supported Chains

The function is available for all chains that have both `fungible_balances_daily` and `fungible_credit_debit` tables:

| Type | Chains |
| - | - |
| EVM | apechain, arbitrum, avalanche, b3, base, berachain, blast, bsc, celo, core, ethereum, hyperevm, ink, linea, megaeth, monad, optimism, plasma, polygon, scroll, soneium, sonic, stable, tempo, unichain, vana, worldchain |
| Move | sui, aptos |

<Note>
  For EVM chains, input addresses are automatically lowercased. For non-EVM chains (SUI, Aptos), addresses are used as-is.
</Note>

### Granular Balances

* In `fungible_balances`/`balances`, balances model, each entry corresponds to a specific event/transaction that causes a balance change in a particular asset at the block level.
* This means **a new entry is only created when a transaction alters an asset's balance at the block level.**
* For example, if a wallet receives 1 ETH in 2015 and experiences no further changes until yesterday, the model will have two entries: one for the initial receipt in 2015 and another for the recent change

Use Cases:

* Track granular, block-level changes of address and token address pairs whenever there are changes in the balance of assets