> ## 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.
# Table Reference
> Column-level schema and example queries for the allium_identity.geo tables
## Table Overview
All tables live in the **`allium_identity.geo`** schema.
| # | Table | Grain | Rows (approx.) |
| - | -------------------------------------- | -------------------------------------------------------------- | -------------- |
| 1 | `master_list` | (chain, address) | \~80M |
| 2 | `addresses_geography` | (chain, address) | \~20M |
| 3 | `addresses_timezones` | (chain, address) | \~166M |
| 4 | `coverage_summary` | (chain, measurability, wallet\_type, hosted\_subtype) | \~50 |
| 5 | `exchange_country_attribution` | exchange | 365 |
| 6 | `exchange_gravity_weekly` | (week\_start, exchange, direction, country) | weekly |
| 7 | `entity_flows_weekly` | (week\_start, token, from\_entity, to\_entity, classification) | weekly |
| 8 | `country_corridors_weekly` | (week\_start, token, from\_country, to\_country) | weekly |
| 9 | `country_corridors_distributed_weekly` | (week\_start, token, from\_country, to\_country) | weekly |
For enum/field-value definitions see the [Field Values Reference](/historical-data/identity/geo/reference).
**Chain values differ across tables.** `master_list` and `coverage_summary` use per-chain values (ethereum, polygon, …). `addresses_geography` and `addresses_timezones` collapse all EVM chains into `evm`, so their `chain` is one of `evm` / `solana` / `tron`. Joining these tables on `chain` requires mapping EVM chains to `evm` — see [Joining](/historical-data/identity/geo/reference#chain-values--joining).
***
## 1. Master List
**Table**: `allium_identity.geo.master_list`
The **canonical classification** for every address across the 12 supported chains: eligibility (measurability), wallet type (hosted vs unhosted), and — for hosted local/regional exchanges — an operating country.
**Grain**: One row per (chain, address). **Chain values**: per-chain.
| Column | Type | Description |
| ----------------------------- | --------- | ----------------------------------------------------------------------------- |
| `chain` | VARCHAR | Blockchain (per-chain value) |
| `address` | VARCHAR | Wallet address (case-sensitive for Solana/Tron) |
| `measurability` | VARCHAR | `potentially_measurable` or `not_measurable` |
| `not_measurable_reason` | VARCHAR | `contract`, `token`, `infrastructure`, `genesis` (NULL when measurable) |
| `wallet_type` | VARCHAR | `hosted`, `unhosted`, or NULL |
| `hosted_subtype` | VARCHAR | `global_exchange`, `local_exchange`, `regional_exchange` (NULL if not hosted) |
| `hosted_geo_country` | VARCHAR | Operating country for **local** exchanges |
| `hosted_geo_country_code` | VARCHAR | ISO 3166-1 alpha-2 code |
| `hosted_geo_region` | VARCHAR | Allium region (`apac`/`emea`/`americas`) for local/regional exchanges |
| `_created_at` / `_updated_at` | TIMESTAMP | Row timestamps |
`not_measurable` is a small hard-excluded set (\~0.06% of rows: contracts, tokens, infra, genesis). The large "unattributed" population is `potentially_measurable` addresses with no confident country yet — absent from `addresses_geography`, not flagged here.
**Example — measurability breakdown by chain**:
```sql theme={null}
SELECT chain, measurability, not_measurable_reason, COUNT(*) AS address_count
FROM allium_identity.geo.master_list
GROUP BY 1, 2, 3
ORDER BY 1, address_count DESC;
```
***
## 2. Addresses Geography
**Table**: `allium_identity.geo.addresses_geography`
**Country-level attribution** for addresses with a confident signal. Combines label-derived country signals with flow-based wallet-relatedness propagation.
**Grain**: One row per (chain, address). **Chain values**: `evm`, `solana`, `tron`. **Coverage**: \~20M addresses.
| Column | Type | Description |
| ----------------- | ------- | ---------------------------------------------------------------------------------- |
| `address` | VARCHAR | Wallet address |
| `chain` | VARCHAR | `evm`, `solana`, or `tron` |
| `primary_country` | VARCHAR | Attributed country name (e.g. `United States`, `South Korea`) |
| `primary_region` | VARCHAR | Allium region: `apac`, `emea`, `americas` |
| `score` | FLOAT | Raw attribution strength (higher = stronger; **not** 0–1) |
| `confidence` | VARCHAR | Conviction tier: `Very High` / `High` / `Moderate` / `Low` / `Very Low Conviction` |
| `reasoning` | VARCHAR | Free-text explanation of the signals used |
Filter on `confidence` (the conviction tier), **not** on a numeric `score` threshold.
**Example — top countries at high conviction**:
```sql theme={null}
SELECT primary_country, primary_region, COUNT(*) AS addresses
FROM allium_identity.geo.addresses_geography
WHERE confidence IN ('Very High Conviction', 'High Conviction')
AND primary_country IS NOT NULL
GROUP BY 1, 2
ORDER BY addresses DESC
LIMIT 20;
```
***
## 3. Addresses Timezones
**Table**: `allium_identity.geo.addresses_timezones`
**Timezone inference** from transaction-timing patterns, percentile-rank calibrated. Requires ≥ 10 transactions; CEX, MEV, manual-labeled, and contract addresses are excluded.
**Grain**: One row per (chain, address). **Chain values**: `evm`, `solana`, `tron`. **Rows**: \~166M.
| Column | Type | Description |
| --------------------- | ------- | ----------------------------------------------------------------- |
| `address` | VARCHAR | Wallet address |
| `chain` | VARCHAR | `evm`, `solana`, or `tron` |
| `likely_timezone` | VARCHAR | Inferred region profile |
| `separation_score` | FLOAT | Distinctness of best region vs runner-up (0–1) |
| `absolute_confidence` | FLOAT | Confidence from closeness to a region profile |
| `sample_confidence` | FLOAT | Confidence from transaction count |
| `confidence_score` | FLOAT | Calibrated composite (percentile rank, 0–1) |
| `conviction_level` | VARCHAR | `Very High` / `High` / `Moderate` / `Low` / `Very Low Conviction` |
Conviction thresholds are percentile-based: `Very High` ≈ top 1%, `High` ≈ top 5%, `Moderate` ≈ top 20%, `Low` ≈ top 40%, else `Very Low`.
Timezone ≠ country: use `addresses_geography` for country attribution.
***
## 4. Coverage Summary
**Table**: `allium_identity.geo.coverage_summary`
Pre-aggregated **measurability statistics** by chain, wallet type, and hosted subtype.
**Grain**: One row per (chain, measurability, wallet\_type, hosted\_subtype). **Chain values**: per-chain.
| Column | Type | Description |
| ---------------- | ------- | -------------------------------------------- |
| `chain` | VARCHAR | Blockchain (per-chain) |
| `measurability` | VARCHAR | `potentially_measurable` or `not_measurable` |
| `wallet_type` | VARCHAR | `hosted`, `unhosted`, or NULL |
| `hosted_subtype` | VARCHAR | Hosted subtype (hosted rows only) |
| `wallet_count` | INTEGER | Addresses in this bucket |
| `total_wallets` | INTEGER | Total addresses for the chain |
| `pct_of_total` | FLOAT | `wallet_count` as a % of the chain total |
***
## 5. Exchange Country Attribution
**Table**: `allium_identity.geo.exchange_country_attribution`
**Per-exchange operating-country attribution** for local/regional exchanges, blending SimilarWeb web traffic, on-chain counterparty flows, and the exchange registry. **Global exchanges are excluded here** — their geography is a distribution, served by `exchange_gravity_weekly`.
**Grain**: One row per exchange. **Count**: 365 exchanges.
| Column | Type | Description |
| ---------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `exchange_slug` | VARCHAR | Allium exchange slug (lowercase) |
| `display_name` | VARCHAR | Human-readable exchange name |
| `status` | VARCHAR | `active` or `defunct` |
| `volume_tier` | VARCHAR | `major_global`, `major_local`, `regional`, `unknown` |
| `n_wallets` | INTEGER | Distinct addresses tagged to the exchange (not counterparties) |
| `top_country` | VARCHAR | Highest-scoring country |
| `top_country_code` | VARCHAR | ISO 3166-1 alpha-2 code |
| `top_region` | VARCHAR | Highest-scoring region (majority rule) |
| `likelihood_score` | FLOAT | 0–1 confidence = combined\_score of the #1 country |
| `top_countries` | ARRAY | Top-5 country structs (rank, code, name, region, per-signal shares) |
| `signal_coverage` | OBJECT | `{web_traffic, flows, registry}` booleans |
| `registry_top_country_matches` | BOOLEAN | Registry operating country equals derived `top_country`? |
| `registry_operating_country` / `registry_operating_region` | VARCHAR | Verbatim from the registry |
**Example — exchanges by operating country**:
```sql theme={null}
SELECT top_country, COUNT(*) AS num_exchanges, ROUND(AVG(likelihood_score), 3) AS avg_confidence
FROM allium_identity.geo.exchange_country_attribution
WHERE status = 'active'
GROUP BY 1
ORDER BY num_exchanges DESC;
```
***
## 6. Exchange Gravity Weekly
**Table**: `allium_identity.geo.exchange_gravity_weekly`
**Weekly geographic distribution of flows for global exchanges** (`top_global` + `major_global`, \~30 exchanges including Binance, Coinbase, OKX, Bybit). These exchanges have no single operating country, so instead of one `top_country` this model exposes the **full country distribution** per exchange, direction, and week, derived purely from on-chain flows via a gravity model: each measurable counterparty pulls a slice of the exchange's volume toward its country.
**Grain**: One row per (week\_start, exchange, direction, country). **History**: from 2026-01-01.
| Column | Type | Description |
| ------------------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------- |
| `week_start` | DATE | Monday of the ISO week |
| `global_exchange` | VARCHAR | Exchange slug (binance, coinbase, okx, …) |
| `flow_direction` | VARCHAR | `inbound_deposit` (counterparty → exchange) or `outbound_withdrawal` (exchange → counterparty) |
| `country` | VARCHAR | Counterparty country |
| `region` | VARCHAR | Allium region (`apac`/`emea`/`americas`) |
| `gravity_share` | FLOAT | Country's confidence-weighted share of attributed volume; **sums to 1.0** per (exchange, direction, week) |
| `attributed_volume_usd_country` | FLOAT | Attributed USD volume for this country |
| `wallet_count_country` | INTEGER | Distinct attributed counterparties from this country |
| `avg_confidence_country` | FLOAT | Average attribution confidence for the country |
| `coverage_pct` | FLOAT | `attributed / (attributed + unattributed_addressable)` — how much of addressable volume is geo-attributed |
| `total_volume_usd` | FLOAT | Total volume for (exchange, direction, week) |
| `attributed_volume_usd` / `attributable_volume_usd` | FLOAT | Numerator / denominator of `coverage_pct` |
| `not_measurable_volume_usd` / `other_exchange_volume_usd` | FLOAT | Excluded from the denominator (contracts/infra; CEX-to-CEX settlement) |
| `unattributed_addressable_volume_usd` / `unknown_volume_usd` | FLOAT | Addressable-but-unattributed; not in master\_list |
Counterparty buckets: `geo_attributed` (numerator), `unattributed_addressable` (denominator only), `not_measurable` and `other_exchange` (dropped from the denominator so contracts and CEX-to-CEX settlement don't distort coverage), `unknown` (noise).
**Example — where are Binance deposits coming from? (latest week)**:
```sql theme={null}
SELECT country, region, ROUND(gravity_share, 4) AS share, wallet_count_country
FROM allium_identity.geo.exchange_gravity_weekly
WHERE global_exchange = 'binance'
AND flow_direction = 'inbound_deposit'
AND week_start = (SELECT MAX(week_start) FROM allium_identity.geo.exchange_gravity_weekly)
ORDER BY gravity_share DESC
LIMIT 15;
```
***
## 7. Entity Flows Weekly
**Table**: `allium_identity.geo.entity_flows_weekly`
**Weekly USDC/USDT entity-to-entity flow matrix.** Every adjusted-volume USDC/USDT transfer has its sender and receiver resolved to an *entity*, then aggregated. Country attribution is intentionally absent here — entities are directly known.
**Grain**: One row per (week\_start, token, from\_entity, to\_entity, classification). **History**: from 2020-01-01.
| Column | Type | Description |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `week_start` | DATE | Monday of the ISO week |
| `token` | VARCHAR | `USDC` or `USDT` (bridged/wrapped variants folded to base asset) |
| `from_entity` / `to_entity` | VARCHAR | Resolved entity: label → behavioral segment → wallet type → `unattributed` |
| `from_wallet_type` / `to_wallet_type` | VARCHAR | `hosted`, `unhosted`, `unknown` |
| `from_hosted_subtype` / `to_hosted_subtype` | VARCHAR | Hosted subtype where applicable |
| `from_entity_category` / `to_entity_category` | VARCHAR | `cex`, `dex`, `protocol`, `bridge`, `wallet_classifier`, `unlabeled` |
| `classification` | VARCHAR | Activity bucket from the stablecoin pipeline (e.g. `cex_flow`, `defi`, `payments`, `gambling`, `store_of_value`) |
| `volume_usd` | FLOAT | Total USD volume |
| `transfer_count` | INTEGER | Number of transfers |
Entity resolution order (first non-null wins): `raw_entity` label → wallet-classification **behavioral segment** (Consumer/Institutional/…) → hosted/unhosted `wallet_type` → `unattributed`. Only adjusted-volume transfers are included; `dust`, `mint_burn`, and `infra_automation` are dropped.
**Example — top CEX → DeFi USDC flows (last 8 weeks)**:
```sql theme={null}
SELECT from_entity, to_entity, SUM(volume_usd) AS volume_usd, SUM(transfer_count) AS transfers
FROM allium_identity.geo.entity_flows_weekly
WHERE token = 'USDC'
AND from_entity_category = 'cex'
AND to_entity_category IN ('dex', 'protocol')
AND week_start >= DATEADD(week, -8, CURRENT_DATE())
GROUP BY 1, 2
ORDER BY volume_usd DESC
LIMIT 20;
```
***
## 8. Country Corridors Weekly
**Table**: `allium_identity.geo.country_corridors_weekly`
**Weekly USDC/USDT country-to-country flow matrix, exact attribution only.** Each transfer leg gets a country from the best exact signal; global-exchange legs are carried as `global_cex` (not distributed — see table 9).
**Grain**: One row per (week\_start, token, from\_country, to\_country). **History**: from 2020-01-01.
| Column | Type | Description |
| ------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `week_start` | DATE | Monday of the ISO week |
| `token` | VARCHAR | `USDC` or `USDT` |
| `from_country` / `to_country` | VARCHAR | Canonical country name, `global_cex`, or `unattributed` |
| `from_country_source` / `to_country_source` | VARCHAR | `hosted_country`, `unhosted_geo`, `global_cex`, `unattributed` |
| `from_exchange` / `to_exchange` | VARCHAR | Exchange slug for hosted legs (lets the distributed view join gravity) |
| `is_cross_border` | BOOLEAN | TRUE only when both legs are exact (`hosted_country`/`unhosted_geo`) and countries differ |
| `volume_usd` | FLOAT | Total USD volume |
| `transfer_count` | INTEGER | Number of transfers |
**Per-leg country resolution** (first match wins): global CEX → `global_cex`; hosted local/regional → operating country; unhosted → `addresses_geography` country; else `unattributed`.
**Example — top cross-border USDT corridors (last 12 weeks)**:
```sql theme={null}
SELECT from_country, to_country, SUM(volume_usd) AS volume_usd, SUM(transfer_count) AS transfers
FROM allium_identity.geo.country_corridors_weekly
WHERE token = 'USDT'
AND is_cross_border = TRUE
AND week_start >= DATEADD(week, -12, CURRENT_DATE())
GROUP BY 1, 2
ORDER BY volume_usd DESC
LIMIT 30;
```
***
## 9. Country Corridors Distributed Weekly
**Table**: `allium_identity.geo.country_corridors_distributed_weekly`
**Country corridors with global-exchange legs redistributed** across counterparty countries using `exchange_gravity_weekly`. This is the **expected-value** view: a `global_cex` leg is fanned out by that exchange's weekly gravity shares (withdrawal shares for a from-leg, deposit shares for a to-leg). Shares sum to 1.0, so total volume is conserved.
**Grain**: One row per (week\_start, token, from\_country, to\_country). **History**: from 2020-01-01.
| Column | Type | Description |
| ------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `week_start` | DATE | Monday of the ISO week |
| `token` | VARCHAR | `USDC` or `USDT` |
| `from_country` / `to_country` | VARCHAR | Canonical country name (global-CEX legs resolved to countries) |
| `from_country_source` / `to_country_source` | VARCHAR | Attribution source of each leg |
| `is_cross_border` | BOOLEAN | Both legs resolved to different, non-`unattributed`/`global_cex` countries |
| `distributed_volume_usd` | FLOAT | Expected-value volume = `volume_usd × from_weight × to_weight` |
Transfer counts are **not** distributed (a transfer can't be split), so this view has no `transfer_count`. Use `country_corridors_weekly` for exact corridors and counts; use this view for total country-to-country volume including global-exchange flows.
**Example — net USDT flow balance per country (last 8 weeks)**:
```sql theme={null}
WITH f AS (
SELECT to_country AS country, SUM(distributed_volume_usd) AS inflow, 0 AS outflow
FROM allium_identity.geo.country_corridors_distributed_weekly
WHERE token = 'USDT' AND week_start >= DATEADD(week, -8, CURRENT_DATE())
AND to_country NOT IN ('unattributed', 'global_cex')
GROUP BY 1
UNION ALL
SELECT from_country, 0, SUM(distributed_volume_usd)
FROM allium_identity.geo.country_corridors_distributed_weekly
WHERE token = 'USDT' AND week_start >= DATEADD(week, -8, CURRENT_DATE())
AND from_country NOT IN ('unattributed', 'global_cex')
GROUP BY 1
)
SELECT country, SUM(inflow) AS inflow_usd, SUM(outflow) AS outflow_usd,
SUM(inflow) - SUM(outflow) AS net_usd
FROM f GROUP BY 1 ORDER BY ABS(SUM(inflow) - SUM(outflow)) DESC LIMIT 30;
```
***
## Data Freshness
| Table | Update frequency |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `master_list`, `addresses_geography`, `coverage_summary` | Weekly |
| `addresses_timezones` | Daily |
| `exchange_country_attribution` | Periodic (registry/web/flow refresh) |
| `exchange_gravity_weekly`, `entity_flows_weekly`, `country_corridors_weekly`, `country_corridors_distributed_weekly` | Weekly (4-week incremental lookback on the flow tables) |
## Next Steps
Compliance, regional analysis, exchange gravity, and cross-border flow recipes
Data dictionary, data quality, and best practices