Skip to main content
A consolidated reference for the categorical fields across the allium_identity.geo tables, plus data-quality caveats and query best practices. For full column lists see the Table Reference.

​
measurability & not_measurable_reason

master_list.measurability — whether an address is eligible for attribution.
ValueMeaning
potentially_measurableOrganic wallet eligible for attribution (~99.9% of rows)
not_measurableHard-excluded infrastructure (see reason)
master_list.not_measurable_reason — why an address is excluded (NULL when measurable).
ValueWhat it flags
contractSmart-contract address
tokenToken / token-blacklist contract
infrastructureBridge, chain/system, or other infra
genesisGenesis / burn address (0x0…0, 0x…dead, …)

​
wallet_type & hosted_subtype

master_list.wallet_type and hosted_subtype.
wallet_typeProfile
hostedCustodial — an exchange holds the funds
unhostedSelf-custody — the user holds the keys
NULLNot measurable
hosted_subtypeDescriptionCountry field
global_exchangeMajor CEX serving many countriesnone (no per-wallet country)
local_exchangeSingle-country CEXhosted_geo_country + hosted_geo_region
regional_exchangeMulti-country regional CEXhosted_geo_region

​
conviction tiers (confidence / conviction_level)

Both addresses_geography.confidence and addresses_timezones.conviction_level use the same five-tier scale. This is the field to filter on — not a numeric score.
ValueRough selectivityRecommended use
Very High Conviction~top 1%Compliance / KYC
High Conviction~top 5%Compliance, high-trust analysis
Moderate Conviction~top 20%Regional analysis
Low Conviction~top 40%Exploration only
Very Low ConvictionremainderExploration only; weak signal
addresses_geography.score is a raw attribution strength (observed range ~0–47, mostly < 1) — it is not a 0–1 probability and thresholds like score >= 0.7 are meaningless. Always filter on the conviction tier.

​
reasoning (free text)

addresses_geography.reasoning is not an enum — it is a human-readable explanation of the signals behind each attribution, e.g. “Propagated from 20 related wallet(s) via shared funders within a 24-72h window.” or “Countries disagree. … Selected deposit country based on higher score (685 vs 270).” Use it for auditing individual rows; don’t GROUP BY it expecting a small set of values.

​
primary_region

addresses_geography.primary_region and exchange top_region / hosted_geo_region use Allium’s three-region grouping: apac, emea, americas (lowercase).

​
exchange status & volume_tier

exchange_country_attribution.status: active, defunct. exchange_country_attribution.volume_tier: major_global, major_local, regional, unknown. Global exchanges (top_global) are excluded from exchange_country_attribution entirely — their per-country distribution lives in exchange_gravity_weekly.

​
flow_direction (exchange_gravity_weekly)

ValueMeaning
inbound_depositCounterparty → exchange (where deposits come from)
outbound_withdrawalExchange → counterparty (where withdrawals go)
gravity_share sums to 1.0 across countries per (exchange, direction, week). coverage_pct = attributed ÷ (attributed + unattributed_addressable) — not_measurable and other_exchange (CEX-to-CEX settlement) volume is excluded from the denominator.

​
entity_category & classification (entity_flows_weekly)

from_entity_category / to_entity_category: cex, dex, protocol, bridge, wallet_classifier (typed by behavioral segment, no hard label), unlabeled. from_wallet_type / to_wallet_type: hosted, unhosted, unknown. classification is the stablecoin-pipeline activity bucket carried through from enriched_transfers (e.g. cex_flow, defi, payments, gambling, store_of_value); dust, mint_burn, and infra_automation are excluded from this table. token: USDC or USDT (bridged/wrapped variants folded to the base asset).

​
country_source (country_corridors_weekly)

from_country_source / to_country_source — how each leg’s country was resolved:
ValueMeaning
hosted_countryLocal/regional exchange operating country (exact)
unhosted_geoUnhosted wallet country from addresses_geography (exact)
global_cexGlobal-exchange leg — no single country; distributed in country_corridors_distributed_weekly
unattributedNo country available
is_cross_border = TRUE only when both legs are exact (hosted_country/unhosted_geo) and the countries differ. In country_corridors_distributed_weekly, global_cex legs are fanned out by exchange_gravity_weekly shares and distributed_volume_usd replaces volume_usd (transfer counts are not distributed).

​
Chain values & joining

chain is not encoded the same way across tables:
Tablechain values
master_list, coverage_summaryper-chain: ethereum, polygon, arbitrum, base, optimism, bsc, avalanche, linea, scroll, blast, tron, solana
addresses_geography, addresses_timezonesevm, solana, tron (all EVM chains collapsed to evm)
To join master_list to addresses_geography/addresses_timezones, map EVM chains to evm first: 
CASE WHEN chain IN ('solana', 'tron') THEN chain ELSE 'evm' END AS chain_family
A naive master_list.chain = addresses_geography.chain join returns zero EVM rows.

​
Data Quality & Limitations

  1. Attribution coverage ≈ 25%. ~20M of ~80M classified addresses have a country in addresses_geography. The rest are potentially_measurable but lack a confident signal (mostly unlabeled self-custody wallets), not hard-excluded not_measurable infra.
  2. Country propagation is partial. Flow-based relatedness propagation runs on ethereum, polygon, base, solana, and tron (EVM chains surface as evm). Other EVM chains rely on labels and timezone signals only, so their coverage is lower.
  3. Global-exchange geography is a distribution. Binance/Coinbase-style global exchanges get no single country; use exchange_gravity_weekly (and the distributed corridors view) for their per-country flow shares, and check coverage_pct before trusting a given week.
  4. Flow tables are USDC/USDT only. entity_flows_weekly and the corridor tables cover the canonical USDC/USDT deployment set on adjusted volume; they are not all-token or all-stablecoin.
  5. Timezone ≠ country. addresses_timezones infers a region profile from activity timing; treat it as a supporting signal, not a country.

​
Best Practices

​
1. Filter by conviction, not score

-- GOOD
WHERE confidence IN ('Very High Conviction', 'High Conviction')

-- BAD (score is not a 0–1 probability)
WHERE score >= 0.7

​
2. Use country names exactly as stored

primary_country holds short-form names (e.g. United States, South Korea, Iran), sourced from seeds_allium_registry__countries — not ISO long forms. 
-- GOOD
WHERE primary_country = 'United States'

-- BAD (won't match)
WHERE primary_country IN ('United States of America', 'US', 'USA')

​
3. Map chains before joining

See Chain values & joining. Map EVM chains to evm before joining per-chain tables to the collapsed ones.

​
4. Separate hosted from unhosted

A country on a local exchange wallet is an operating jurisdiction; a country on an unhosted wallet is an inferred user location. Filter master_list.wallet_type to the one you mean rather than mixing them.

​
5. not_measurable is not “no country”

not_measurable in master_list flags contracts/tokens/infra/genesis (~0.06% of rows). The much larger set of addresses without a country are potentially_measurable and simply absent from addresses_geography.

​
6. Case sensitivity

Address case varies by chain — preserve case when joining on address for Solana/Tron.
ChainCase sensitive?
Solana, Tron✅ Yes (preserve case)
EVM❌ No
-- GOOD (Solana): preserve case
JOIN allium_identity.geo.addresses_geography g
  ON g.chain = 'solana' AND g.address = t.address

-- BAD: lowercasing breaks Solana joins
JOIN allium_identity.geo.addresses_geography g
  ON g.chain = 'solana' AND LOWER(g.address) = LOWER(t.address)

​
Support & Updates

For questions, data quality issues, or feature requests related to geographic intelligence:

​
Next Steps

Example Queries

Compliance, regional analysis, and exchange attribution recipes

Geographic Intelligence

Back to the geographic intelligence overview