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

# Field Values Reference

> Data dictionary, data quality, and best practices for the allium_identity.geo schema

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](/historical-data/identity/geo/tables).

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

<Warning>
  `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.
</Warning>

## 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:

```sql theme={null}
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

```sql theme={null}
-- 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.

```sql theme={null}
-- 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](#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         |

```sql theme={null}
-- 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](mailto:data@allium.so)

## Next Steps

<CardGroup cols={2}>
  <Card title="Example Queries" icon="code" href="/historical-data/identity/geo/examples">
    Compliance, regional analysis, and exchange attribution recipes
  </Card>

  <Card title="Geographic Intelligence" icon="earth-americas" href="/historical-data/identity/geo">
    Back to the geographic intelligence overview
  </Card>
</CardGroup>