Field Values Reference

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.

Value	Meaning
`potentially_measurable`	Organic wallet eligible for attribution (~99.9% of rows)
`not_measurable`	Hard-excluded infrastructure (see reason)

master_list.not_measurable_reason — why an address is excluded (NULL when measurable).

Value	What it flags
`contract`	Smart-contract address
`token`	Token / token-blacklist contract
`infrastructure`	Bridge, chain/system, or other infra
`genesis`	Genesis / burn address (`0x0…0`, `0x…dead`, …)

wallet_type & hosted_subtype

master_list.wallet_type and hosted_subtype.

wallet_type	Profile
`hosted`	Custodial — an exchange holds the funds
`unhosted`	Self-custody — the user holds the keys
`NULL`	Not measurable

hosted_subtype	Description	Country field
`global_exchange`	Major CEX serving many countries	none (no per-wallet country)
`local_exchange`	Single-country CEX	`hosted_geo_country` + `hosted_geo_region`
`regional_exchange`	Multi-country regional CEX	`hosted_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.

Value	Rough selectivity	Recommended 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 Conviction`	remainder	Exploration 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)

Value	Meaning
`inbound_deposit`	Counterparty → exchange (where deposits come from)
`outbound_withdrawal`	Exchange → 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:

Value	Meaning
`hosted_country`	Local/regional exchange operating country (exact)
`unhosted_geo`	Unhosted wallet country from `addresses_geography` (exact)
`global_cex`	Global-exchange leg — no single country; distributed in `country_corridors_distributed_weekly`
`unattributed`	No 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:

Table	`chain` values
`master_list`, `coverage_summary`	per-chain: ethereum, polygon, arbitrum, base, optimism, bsc, avalanche, linea, scroll, blast, tron, solana
`addresses_geography`, `addresses_timezones`	`evm`, `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

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.
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.
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.
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.
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.

Chain	Case 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:

Slack: #data-quality or #ask-data-team
Email: data@allium.so

Next Steps

Example Queries

Compliance, regional analysis, and exchange attribution recipes

Geographic Intelligence

Back to the geographic intelligence overview

Overview

Data Verticals

Solana

Hyperliquid

Lighter

Bitcoin Ecosystem

EVM

Cosmos Ecosystem

Move Ecosystem

Other Ecosystems

measurability & not_measurable_reason

wallet_type & hosted_subtype

conviction tiers (confidence / conviction_level)

reasoning (free text)

primary_region

exchange status & volume_tier

flow_direction (exchange_gravity_weekly)

entity_category & classification (entity_flows_weekly)

country_source (country_corridors_weekly)

Chain values & joining

Data Quality & Limitations

Best Practices

1. Filter by conviction, not score

2. Use country names exactly as stored

3. Map chains before joining

4. Separate hosted from unhosted

5. `not_measurable` is not “no country”

6. Case sensitivity

Support & Updates

Next Steps

Example Queries

Geographic Intelligence

​measurability & not_measurable_reason

​wallet_type & hosted_subtype

​conviction tiers (confidence / conviction_level)

​reasoning (free text)

​primary_region

​exchange status & volume_tier

​flow_direction (exchange_gravity_weekly)

​entity_category & classification (entity_flows_weekly)

​country_source (country_corridors_weekly)

​Chain values & joining

​Data Quality & Limitations

​Best Practices

​1. Filter by conviction, not score

​2. Use country names exactly as stored

​3. Map chains before joining

​4. Separate hosted from unhosted

​5. not_measurable is not “no country”

​6. Case sensitivity

​Support & Updates

​Next Steps

Example Queries

Geographic Intelligence

measurability & not_measurable_reason

wallet_type & hosted_subtype

conviction tiers (confidence / conviction_level)

reasoning (free text)

primary_region

exchange status & volume_tier

flow_direction (exchange_gravity_weekly)

entity_category & classification (entity_flows_weekly)

country_source (country_corridors_weekly)

Chain values & joining

Data Quality & Limitations

Best Practices

1. Filter by conviction, not score

2. Use country names exactly as stored

3. Map chains before joining

4. Separate hosted from unhosted

5. `not_measurable` is not “no country”

6. Case sensitivity

Support & Updates

Next Steps