Skip to main content

Table Overview

All tables live in the allium_identity.geo schema.
#TableGrainRows (approx.)
1master_list(chain, address)~80M
2addresses_geography(chain, address)~20M
3addresses_timezones(chain, address)~166M
4coverage_summary(chain, measurability, wallet_type, hosted_subtype)~50
5exchange_country_attributionexchange365
6exchange_gravity_weekly(week_start, exchange, direction, country)weekly
7entity_flows_weekly(week_start, token, from_entity, to_entity, classification)weekly
8country_corridors_weekly(week_start, token, from_country, to_country)weekly
9country_corridors_distributed_weekly(week_start, token, from_country, to_country)weekly
For enum/field-value definitions see the Field Values 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.

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.
ColumnTypeDescription
chainVARCHARBlockchain (per-chain value)
addressVARCHARWallet address (case-sensitive for Solana/Tron)
measurabilityVARCHARpotentially_measurable or not_measurable
not_measurable_reasonVARCHARcontract, token, infrastructure, genesis (NULL when measurable)
wallet_typeVARCHARhosted, unhosted, or NULL
hosted_subtypeVARCHARglobal_exchange, local_exchange, regional_exchange (NULL if not hosted)
hosted_geo_countryVARCHAROperating country for local exchanges
hosted_geo_country_codeVARCHARISO 3166-1 alpha-2 code
hosted_geo_regionVARCHARAllium region (apac/emea/americas) for local/regional exchanges
_created_at / _updated_atTIMESTAMPRow 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:
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.
ColumnTypeDescription
addressVARCHARWallet address
chainVARCHARevm, solana, or tron
primary_countryVARCHARAttributed country name (e.g. United States, South Korea)
primary_regionVARCHARAllium region: apac, emea, americas
scoreFLOATRaw attribution strength (higher = stronger; not 0–1)
confidenceVARCHARConviction tier: Very High / High / Moderate / Low / Very Low Conviction
reasoningVARCHARFree-text explanation of the signals used
Filter on confidence (the conviction tier), not on a numeric score threshold.
Example — top countries at high conviction:
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.
ColumnTypeDescription
addressVARCHARWallet address
chainVARCHARevm, solana, or tron
likely_timezoneVARCHARInferred region profile
separation_scoreFLOATDistinctness of best region vs runner-up (0–1)
absolute_confidenceFLOATConfidence from closeness to a region profile
sample_confidenceFLOATConfidence from transaction count
confidence_scoreFLOATCalibrated composite (percentile rank, 0–1)
conviction_levelVARCHARVery 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.
ColumnTypeDescription
chainVARCHARBlockchain (per-chain)
measurabilityVARCHARpotentially_measurable or not_measurable
wallet_typeVARCHARhosted, unhosted, or NULL
hosted_subtypeVARCHARHosted subtype (hosted rows only)
wallet_countINTEGERAddresses in this bucket
total_walletsINTEGERTotal addresses for the chain
pct_of_totalFLOATwallet_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.
ColumnTypeDescription
exchange_slugVARCHARAllium exchange slug (lowercase)
display_nameVARCHARHuman-readable exchange name
statusVARCHARactive or defunct
volume_tierVARCHARmajor_global, major_local, regional, unknown
n_walletsINTEGERDistinct addresses tagged to the exchange (not counterparties)
top_countryVARCHARHighest-scoring country
top_country_codeVARCHARISO 3166-1 alpha-2 code
top_regionVARCHARHighest-scoring region (majority rule)
likelihood_scoreFLOAT0–1 confidence = combined_score of the #1 country
top_countriesARRAYTop-5 country structs (rank, code, name, region, per-signal shares)
signal_coverageOBJECT{web_traffic, flows, registry} booleans
registry_top_country_matchesBOOLEANRegistry operating country equals derived top_country?
registry_operating_country / registry_operating_regionVARCHARVerbatim from the registry
Example — exchanges by operating country:
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.
ColumnTypeDescription
week_startDATEMonday of the ISO week
global_exchangeVARCHARExchange slug (binance, coinbase, okx, …)
flow_directionVARCHARinbound_deposit (counterparty → exchange) or outbound_withdrawal (exchange → counterparty)
countryVARCHARCounterparty country
regionVARCHARAllium region (apac/emea/americas)
gravity_shareFLOATCountry’s confidence-weighted share of attributed volume; sums to 1.0 per (exchange, direction, week)
attributed_volume_usd_countryFLOATAttributed USD volume for this country
wallet_count_countryINTEGERDistinct attributed counterparties from this country
avg_confidence_countryFLOATAverage attribution confidence for the country
coverage_pctFLOATattributed / (attributed + unattributed_addressable) — how much of addressable volume is geo-attributed
total_volume_usdFLOATTotal volume for (exchange, direction, week)
attributed_volume_usd / attributable_volume_usdFLOATNumerator / denominator of coverage_pct
not_measurable_volume_usd / other_exchange_volume_usdFLOATExcluded from the denominator (contracts/infra; CEX-to-CEX settlement)
unattributed_addressable_volume_usd / unknown_volume_usdFLOATAddressable-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):
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.
ColumnTypeDescription
week_startDATEMonday of the ISO week
tokenVARCHARUSDC or USDT (bridged/wrapped variants folded to base asset)
from_entity / to_entityVARCHARResolved entity: label → behavioral segment → wallet type → unattributed
from_wallet_type / to_wallet_typeVARCHARhosted, unhosted, unknown
from_hosted_subtype / to_hosted_subtypeVARCHARHosted subtype where applicable
from_entity_category / to_entity_categoryVARCHARcex, dex, protocol, bridge, wallet_classifier, unlabeled
classificationVARCHARActivity bucket from the stablecoin pipeline (e.g. cex_flow, defi, payments, gambling, store_of_value)
volume_usdFLOATTotal USD volume
transfer_countINTEGERNumber of transfers
Entity resolution order (first non-null wins): raw_entity label → wallet-classification behavioral segment (Consumer/Institutional/…) → hosted/unhosted wallet_typeunattributed. Only adjusted-volume transfers are included; dust, mint_burn, and infra_automation are dropped.
Example — top CEX → DeFi USDC flows (last 8 weeks):
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.
ColumnTypeDescription
week_startDATEMonday of the ISO week
tokenVARCHARUSDC or USDT
from_country / to_countryVARCHARCanonical country name, global_cex, or unattributed
from_country_source / to_country_sourceVARCHARhosted_country, unhosted_geo, global_cex, unattributed
from_exchange / to_exchangeVARCHARExchange slug for hosted legs (lets the distributed view join gravity)
is_cross_borderBOOLEANTRUE only when both legs are exact (hosted_country/unhosted_geo) and countries differ
volume_usdFLOATTotal USD volume
transfer_countINTEGERNumber 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):
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.
ColumnTypeDescription
week_startDATEMonday of the ISO week
tokenVARCHARUSDC or USDT
from_country / to_countryVARCHARCanonical country name (global-CEX legs resolved to countries)
from_country_source / to_country_sourceVARCHARAttribution source of each leg
is_cross_borderBOOLEANBoth legs resolved to different, non-unattributed/global_cex countries
distributed_volume_usdFLOATExpected-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):
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

TableUpdate frequency
master_list, addresses_geography, coverage_summaryWeekly
addresses_timezonesDaily
exchange_country_attributionPeriodic (registry/web/flow refresh)
exchange_gravity_weekly, entity_flows_weekly, country_corridors_weekly, country_corridors_distributed_weeklyWeekly (4-week incremental lookback on the flow tables)

Next Steps

Example Queries

Compliance, regional analysis, exchange gravity, and cross-border flow recipes

Field Values Reference

Data dictionary, data quality, and best practices