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

# Token Profile (beta)

> Per-token quality signals and grades for filtering price data.

## Overview

`common.tokens.profile_beta` scores every token across liquidity depth,
trading activity, trader concentration, and token legitimacy. Customers join to
`common.prices.hourly` and filter by whatever threshold fits their use case, or
use Allium's built-in grades.

Shipped as **beta**: the table name and classification column carry a `_beta`
suffix. Thresholds and schema may change before GA.

**Coverage**: `ethereum`, `base`, `bsc`, `polygon`, `arbitrum`, `optimism`, `avalanche`, `solana`.

## Sample queries

### Strict (institutional filter)

```sql theme={null}
SELECT p.*
FROM common.prices.hourly p
JOIN common.tokens.profile_beta q USING (chain, address)
WHERE q.allium_classification_beta = 'grade_a'
```

### Custom thresholds

```sql theme={null}
-- Multi-day trading history + non-trivial liquidity
SELECT p.*, q.allium_classification_beta, q.is_realizable
FROM common.prices.hourly p
JOIN common.tokens.profile_beta q USING (chain, address)
WHERE q.active_trading_days_7d >= 2
  AND q.total_pool_liquidity_usd >= 10000
```

### Scope to a chain (or set of chains)

```sql theme={null}
SELECT p.*, q.allium_classification_beta
FROM common.prices.hourly p
JOIN common.tokens.profile_beta q USING (chain, address)
WHERE q.allium_classification_beta IN ('grade_a', 'grade_b')
  AND p.chain IN ('ethereum', 'base', 'solana')
```

### Research (everything with context)

```sql theme={null}
SELECT p.*, q.allium_classification_beta, q.confidence_score,
       q.total_pool_liquidity_usd, q.num_dex_pools, q.hhi_index
FROM common.prices.hourly p
LEFT JOIN common.tokens.profile_beta q USING (chain, address)
```

## How grading works

Three stages:

1. **Signals** — per-token metrics from DEX trades, pool liquidity, trader
   concentration, and the price source registry (7-day rolling window)
2. **Flags** — signals combined into boolean gates (`has_sufficient_liquidity`,
   `has_active_market`, `has_diversified_trading`, `has_stable_price`,
   `has_multi_day_history`, `has_vendor_price`)
3. **Grade** — type-aware cascading CASE assigns `grade_a`, `grade_b`, or `grade_c`.
   Stablecoins are graded against their peg. LSTs against liquidity depth and
   activity. Other tokens against market depth, activity, diversification, and
   price stability.

| Grade     | Meaning                                                   |
| --------- | --------------------------------------------------------- |
| `grade_a` | Deep liquidity, active diversified market, stable pricing |
| `grade_b` | Sufficient liquidity or vendor price, plus active market  |
| `grade_c` | Limited signals — use with independent validation         |

A composite `quality_tier` (1-5) and `quality_score` (0-100) are also exposed
for customers who prefer numeric filters.

## Schema

Unique key: `(chain, address)`. One row per token per chain.

### Identity

| Column       | Description                                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| `chain`      | Blockchain (lowercase): `ethereum`, `base`, `bsc`, `polygon`, `arbitrum`, `optimism`, `avalanche`, `solana` |
| `address`    | Token contract address (lowercase)                                                                          |
| `symbol`     | Token symbol                                                                                                |
| `token_type` | `stablecoin` / `lst` / `other` (from curated registries; `other` = default)                                 |

### Pool liquidity

| Column                       | Description                                    |
| ---------------------------- | ---------------------------------------------- |
| `total_pool_liquidity_usd`   | Sum of USD across all pools holding this token |
| `num_dex_pools`              | Count of distinct pools                        |
| `largest_pool_liquidity_usd` | USD in the largest single pool                 |
| `top_pool_weight_pct`        | Largest pool's share of total liquidity (0-1)  |

### Trading activity (7d rolling)

| Column                   | Description                              |
| ------------------------ | ---------------------------------------- |
| `avg_daily_volume_usd`   | Mean daily USD volume                    |
| `avg_hourly_traders`     | Mean unique traders per hour             |
| `avg_hourly_trades`      | Mean trade count per hour                |
| `active_hours_7d`        | Count of hours with activity (max 168)   |
| `activity_consistency`   | `active_hours_7d / 168`                  |
| `active_trading_days_7d` | Count of distinct UTC days with activity |

### Price quality

| Column                           | Description                                         |
| -------------------------------- | --------------------------------------------------- |
| `price_max_min_ratio_7d`         | Max price / min price over 7d                       |
| `price_coefficient_of_variation` | stddev(price) / avg(price)                          |
| `median_safe_price_coverage`     | Fraction of hours with a non-null median safe price |
| `price_source`                   | `dex`, `provider_a`, or `static_price_mapping`      |

### Market structure

| Column                   | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| `hhi_index`              | Herfindahl index of trader volume shares (0-1). Low = diversified |
| `top5_trader_volume_pct` | Volume share of the top 5 traders (0-100)                         |
| `unique_traders_7d`      | Count of distinct trader addresses                                |

### Stablecoin-specific

| Column              | Description                        |
| ------------------- | ---------------------------------- |
| `peg_deviation_pct` | For stablecoins: `\|price - 1.0\|` |

### Boolean flags

| Column                     | True when                                                     |
| -------------------------- | ------------------------------------------------------------- |
| `has_vendor_price`         | `price_source = 'provider_a'`                                 |
| `has_sufficient_liquidity` | Pool liquidity passes the floor                               |
| `has_active_market`        | Trader count, trade count, and volume all pass floors         |
| `has_stable_price`         | 7d price range is within bounds                               |
| `has_diversified_trading`  | Trader concentration below threshold                          |
| `has_multi_day_history`    | Active on at least one day in the window                      |
| `is_realizable`            | Composite: sufficient liquidity + active market + diversified |

### Composite grades

| Column                       | Description                       |
| ---------------------------- | --------------------------------- |
| `allium_classification_beta` | `grade_a` / `grade_b` / `grade_c` |
| `quality_tier`               | 1-5 (numeric, monotonic)          |
| `quality_score`              | 0-100                             |
| `confidence_score`           | 0-100, type-aware weighted        |

## Limitations

* **Beta thresholds will be tuned.** Schema values you filter on
  (`allium_classification_beta`, `quality_tier`, the raw signals) remain stable;
  the grade boundaries themselves may shift as we collect customer feedback.
* **Solana grading is sparser.** Solana's long tail of low-activity tokens is
  reflected in the grade distribution (the vast majority land in `grade_c`).
  Filter on `is_realizable` or `allium_classification_beta IN ('grade_a','grade_b')`
  for production use cases.

## Methodology

Current threshold values used by the boolean flags. These may be tuned during
beta based on customer feedback.

| Flag                       | Condition                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| `has_sufficient_liquidity` | `total_pool_liquidity_usd >= 10,000`                                                        |
| `has_active_market`        | `avg_hourly_traders >= 2` AND `avg_hourly_trades >= 3` AND `avg_daily_volume_usd >= 10,000` |
| `has_stable_price`         | `price_max_min_ratio_7d <= 10` OR price ratio is null                                       |
| `has_diversified_trading`  | `hhi_index <= 0.15` (US DOJ antitrust standard for "competitive")                           |
| `has_multi_day_history`    | `active_trading_days_7d >= 1`                                                               |

Grade thresholds (stablecoin branch):

| Check                             | Threshold        |
| --------------------------------- | ---------------- |
| `peg_deviation_pct` for `grade_a` | `< 0.005` (0.5%) |
| `num_dex_pools` for `grade_a`     | `>= 2`           |

Grade thresholds (LST and other branches):

| Check                                    | Threshold                                       |
| ---------------------------------------- | ----------------------------------------------- |
| `total_pool_liquidity_usd` for `grade_a` | `>= 100,000`                                    |
| `has_vendor_price` alternative           | vendor presence substitutes for liquidity floor |