> ## 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.
# Aggregates
> Entity, category and geography rollups built on top of Allium Identity labels
# Identity Aggregates
Pre-aggregated rollups of labeled activity — balances and flows grouped by
entity, category or attributed country. These sit on top of
[`address_labels`](/historical-data/identity/premium#the-table), so anything not attributed
by the labeling pipeline is not represented here.
All tables live in the **`allium_identity.aggregates`** schema.
## Table Overview
| Table | Rows (approx.) |
| -------------------------------------------------------------------------------- | -------------- |
| [`entity_wallet_registry`](#entity-wallet-registry) | \~148M |
| [`cex_deposits_withdrawals`](#cex-deposits-and-withdrawals) | view |
| [`cex_attributed_flows`](#cex-attributed-flows) | \~3.2M |
| [`entity_balances_daily`](#entity-balances-daily) | view |
| [`category_balances_daily`](#category-balances-daily) | view |
| [`geo_balances_daily`](#geo-balances-daily) | view |
| [`geo_balances_exchanges_added_daily`](#geo-balances-with-exchanges-added-daily) | view |
| [`stablecoin_top_holders`](#stablecoin-top-holders) | view |
Each table's grain is listed in its section below.
Balance tables carry `usd_balance` computed at snapshot time. Tokens without
price coverage have a null `usd_balance` while `balance` is still populated, so
filter on `usd_balance IS NOT NULL` when summing USD.
## Entity Wallet Registry
`allium_identity.aggregates.entity_wallet_registry`
Registry mapping anonymized wallet IDs to their attributed entity, category, and attribution metadata. Used as the join key between entity\_balances\_daily and real address data.
**Grain:** one row per `(wallet_id, primary_entity)`
| Column Name | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| wallet\_id | Anonymized identifier for a wallet in the entity\_balances\_daily dataset. Maps to a real address via entity\_wallet\_registry with IP protections applied. |
| primary\_entity | Name of the primary attributed entity (e.g. exchange or protocol name). |
| primary\_category | Primary category of the attributed entity (e.g. `exchange`, `defi`, `bridge`). |
| anonymized\_label | Anonymized entity label used in entity\_balances\_daily to protect IP while preserving attributional structure for analytics. |
| first\_txn\_block\_timestamp | Block timestamp of the wallet's first recorded transaction across all supported chains. |
| first\_activity\_chain | Chain on which the wallet first appeared in the transaction record. |
| attribution\_date | Calendar date (UTC) for which address attribution scores were computed. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |
## CEX Deposits and Withdrawals
`allium_identity.aggregates.cex_deposits_withdrawals`
Daily aggregated deposit and withdrawal volumes per entity, chain, and token. Captures deposits (amount\_in) and withdrawals (amount\_out) between entity wallets and CEX addresses.
**Grain:** one row per `(date, entity, chain, token_address)`
| Column Name | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| date | Calendar date (UTC) this record represents. Used in daily aggregate tables. |
| entity | Name or label of the entity (organization, protocol, or project) associated with this record. Used in app\_users and identity models. |
| chain | Slug identifying the blockchain this record belongs to (e.g. `ethereum`, `base`, `avalanche`, `solana`). In per-chain tables this is always the same value; in cross-chain tables it identifies which chain the row came from. |
| token\_address | Contract address of the token. For EVM chains, native currency (e.g. ETH, MATIC) is represented as the zero address (0x0000000000000000000000000000000000000000). For Solana, this is the mint address. |
| token\_symbol | Ticker symbol of the token (e.g. "USDC", "WETH"). |
| token\_name | Full name of the token (e.g. "USD Coin", "Wrapped Ether"). |
| amount\_in | Total token amount deposited during the period, in native units. |
| amount\_out | Total token amount withdrawn during the period, in native units. |
| usd\_amount\_in | Total USD value deposited during the period, computed from amount\_in using exchange rates at transfer time. |
| usd\_amount\_out | Total USD value withdrawn during the period, computed from amount\_out using exchange rates at transfer time. |
| net\_usd\_amount | Net USD flow for the period: usd\_amount\_in minus usd\_amount\_out. Positive means net deposits, negative means net withdrawals. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |
## CEX Attributed Flows
`allium_identity.aggregates.cex_attributed_flows`
Cross-entity flow aggregates attributed to centralized exchanges. Each row captures a directional flow between two entities (from\_entity → to\_entity) for a given chain, token, and date, with category and grain classification on both sides.
**Grain:** one row per `(date, chain, from_key, to_key, token_address)`
| Column Name | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| date | Calendar date (UTC) this record represents. Used in daily aggregate tables. |
| chain | Slug identifying the blockchain this record belongs to (e.g. `ethereum`, `base`, `avalanche`, `solana`). In per-chain tables this is always the same value; in cross-chain tables it identifies which chain the row came from. |
| from\_key | Composite key for the source entity, combining entity name and category. Used to join or group attributed flows by origin. |
| to\_key | Composite key for the destination entity, combining entity name and category. Used to join or group attributed flows by destination. |
| from\_entity | Name of the source entity in the attributed flow. |
| from\_category | Category of the source entity (e.g., cex, defi, individual, bridge). |
| from\_grain | Attribution granularity of the source: entity (specific name known), category (type known, name unknown), or chain (chain-level only). |
| to\_entity | Name of the destination entity in the attributed flow. |
| to\_category | Category of the destination entity (e.g., cex, defi, individual, bridge). |
| to\_grain | Attribution granularity of the destination: entity, category, or chain. |
| token\_address | Contract address of the token. For EVM chains, native currency (e.g. ETH, MATIC) is represented as the zero address (0x0000000000000000000000000000000000000000). For Solana, this is the mint address. |
| token\_symbol | Ticker symbol of the token (e.g. "USDC", "WETH"). |
| token\_name | Full name of the token (e.g. "USD Coin", "Wrapped Ether"). |
| amount | Token amount normalized by the token's decimal precision (amount\_raw / 10^decimals). This is the human-readable value (e.g. 1.5 USDC rather than 1500000). |
| usd\_amount | USD value of the token amount at the time of the event, computed using the hourly USD exchange rate. |
| transfer\_count | Number of individual transfers aggregated into this row. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |
## Entity Balances Daily
`allium_identity.aggregates.entity_balances_daily`
Daily stablecoin and native token balance snapshots for attributed entity wallets over a rolling window. Uses anonymized wallet IDs to protect IP while preserving attributional structure.
**Grain:** one row per `(date, entity, chain, token_address)`
| Column Name | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| date | Calendar date (UTC) this record represents. Used in daily aggregate tables. |
| entity | Name or label of the entity (organization, protocol, or project) associated with this record. Used in app\_users and identity models. |
| category | Category or classification label for this record. The specific taxonomy depends on the model context (e.g. token category, transfer category, metric category). |
| chain | Slug identifying the blockchain this record belongs to (e.g. `ethereum`, `base`, `avalanche`, `solana`). In per-chain tables this is always the same value; in cross-chain tables it identifies which chain the row came from. |
| token\_address | Contract address of the token. For EVM chains, native currency (e.g. ETH, MATIC) is represented as the zero address (0x0000000000000000000000000000000000000000). For Solana, this is the mint address. |
| token\_symbol | Ticker symbol of the token (e.g. "USDC", "WETH"). |
| balance | Token balance normalized by the token's decimal precision (raw\_balance / 10^decimals). Human-readable value (e.g. 1.5 USDC rather than 1500000). |
| usd\_balance | USD value of the token balance, computed using the exchange rate at the time of the balance snapshot. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |
| \_price\_updated\_at | Timestamp (UTC) when the price used to value this row's `usd_balance` was last changed upstream. NULL for unpriced tokens. Advances only for price changes the hourly incremental actually recomputed (recent hours within the rolling window, or a full-refresh/patch); silent corrections to older prices outside that window are not reflected. |
## Category Balances Daily
`allium_identity.aggregates.category_balances_daily`
Daily stablecoin and native token balance snapshots rolled up to entity category grain (CEX, DEX, bridge, lending, etc.). Sums all entity-level balances within each principal\_category. One row per (date, category, chain, token\_address).
**Grain:** one row per `(date, category, chain, token_address)`
| Column Name | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| date | Calendar date (UTC) this record represents. Used in daily aggregate tables. |
| category | Category or classification label for this record. The specific taxonomy depends on the model context (e.g. token category, transfer category, metric category). |
| chain | Slug identifying the blockchain this record belongs to (e.g. `ethereum`, `base`, `avalanche`, `solana`). In per-chain tables this is always the same value; in cross-chain tables it identifies which chain the row came from. |
| token\_address | Contract address of the token. For EVM chains, native currency (e.g. ETH, MATIC) is represented as the zero address (0x0000000000000000000000000000000000000000). For Solana, this is the mint address. |
| token\_symbol | Ticker symbol of the token (e.g. "USDC", "WETH"). |
| balance | Token balance normalized by the token's decimal precision (raw\_balance / 10^decimals). Human-readable value (e.g. 1.5 USDC rather than 1500000). |
| usd\_balance | USD value of the token balance, computed using the exchange rate at the time of the balance snapshot. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |
## Geo Balances Daily
`allium_identity.aggregates.geo_balances_daily`
Daily balance snapshots for wallets with geographic attribution, broken down by primary country and region. Extends entity\_balances\_daily with geo signals.
**Grain:** one row per `(date, primary_country, chain, token_address)`
| Column Name | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| date | Calendar date (UTC) this record represents. Used in daily aggregate tables. |
| primary\_country | Inferred primary country for a wallet or entity, derived from geographic attribution signals (exchange deposit/withdrawal patterns and timezone inference). |
| primary\_region | World region corresponding to primary\_country (e.g., Europe, North America, Southeast Asia). |
| chain | Slug identifying the blockchain this record belongs to (e.g. `ethereum`, `base`, `avalanche`, `solana`). In per-chain tables this is always the same value; in cross-chain tables it identifies which chain the row came from. |
| token\_address | Contract address of the token. For EVM chains, native currency (e.g. ETH, MATIC) is represented as the zero address (0x0000000000000000000000000000000000000000). For Solana, this is the mint address. |
| token\_symbol | Ticker symbol of the token (e.g. "USDC", "WETH"). |
| balance | Token balance normalized by the token's decimal precision (raw\_balance / 10^decimals). Human-readable value (e.g. 1.5 USDC rather than 1500000). |
| usd\_balance | USD value of the token balance, computed using the exchange rate at the time of the balance snapshot. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |
## Geo Balances with Exchanges Added Daily
`allium_identity.aggregates.geo_balances_exchanges_added_daily`
Daily balance snapshots for exchange-attributed wallets with geographic classification. Extends geo\_balances\_daily with exchange-depositor address additions.
**Grain:** one row per `(date, primary_country, chain, token_address)`
| Column Name | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| date | Calendar date (UTC) this record represents. Used in daily aggregate tables. |
| primary\_country | Inferred primary country for a wallet or entity, derived from geographic attribution signals (exchange deposit/withdrawal patterns and timezone inference). |
| chain | Slug identifying the blockchain this record belongs to (e.g. `ethereum`, `base`, `avalanche`, `solana`). In per-chain tables this is always the same value; in cross-chain tables it identifies which chain the row came from. |
| token\_address | Contract address of the token. For EVM chains, native currency (e.g. ETH, MATIC) is represented as the zero address (0x0000000000000000000000000000000000000000). For Solana, this is the mint address. |
| token\_symbol | Ticker symbol of the token (e.g. "USDC", "WETH"). |
| balance | Token balance normalized by the token's decimal precision (raw\_balance / 10^decimals). Human-readable value (e.g. 1.5 USDC rather than 1500000). |
| usd\_balance | USD value of the token balance, computed using the exchange rate at the time of the balance snapshot. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |
## Stablecoin Top Holders
`allium_identity.aggregates.stablecoin_top_holders`
Top stablecoin holders ranked by balance, by chain and token symbol. Includes both chain-scoped and global cross-chain rankings.
**Grain:** one row per `(chain, primary_entity, token_address)`
| Column Name | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| chain | Slug identifying the blockchain this record belongs to (e.g. `ethereum`, `base`, `avalanche`, `solana`). In per-chain tables this is always the same value; in cross-chain tables it identifies which chain the row came from. |
| primary\_entity | Name of the primary attributed entity (e.g. exchange or protocol name). |
| primary\_category | Primary category of the attributed entity (e.g. `exchange`, `defi`, `bridge`). |
| symbol | Ticker symbol of this token or asset. Short alias for `token_symbol` used in tables that preserve the original blockchain field naming convention. |
| token\_address | Contract address of the token. For EVM chains, native currency (e.g. ETH, MATIC) is represented as the zero address (0x0000000000000000000000000000000000000000). For Solana, this is the mint address. |
| stablecoin\_id | Stablecoin ID represented by the concatenation of the stablecoin issuer and symbol. E.g. For USD Coin by Circle, it will be 'circle\_usdc'. |
| total\_balance | Total balance including staked ETH and rewards across all tracked validators. |
| total\_usd\_balance | Total USD balance held by the wallet at the time of update. |
| wallet\_count | Number of distinct wallet addresses in this aggregation bucket. |
| rank\_by\_chain\_symbol | Rank of this holder by balance within the specific chain and token symbol. 1 = largest holder on that chain for that token. |
| rank\_global\_symbol | Rank of this holder by balance across all chains for the same token symbol. 1 = largest cross-chain holder. |
| \_created\_at | Timestamp (UTC) when this row was first written to the Allium platform. Set once on insert and never changed. |
| \_updated\_at | Timestamp (UTC) of the most recent update to this row in the Allium platform. Advances when the row is reprocessed or enriched (e.g. USD price hydration). |