Token Economics

#!/usr/bin/env python3
"""Supply Modeler — Project token supply dynamics over 12 months.

Takes supply parameters (total supply, circulating, emissions, burns, vesting)
and projects monthly supply changes, inflation rates, and FDV/MCap evolution.
Includes scenario analysis with and without burn mechanisms.

Usage:
    python scripts/supply_modeler.py               # runs demo scenario
    python scripts/supply_modeler.py --interactive  # prompts for parameters

Dependencies:
    None (pure math, no external packages)

Environment Variables:
    None required
"""

import argparse
import sys
from typing import Optional


# ── Data Models ─────────────────────────────────────────────────────
class SupplyParams:
    """Parameters for supply projection model."""

    def __init__(
        self,
        name: str,
        total_supply: float,
        circulating_supply: float,
        token_price: float,
        monthly_emissions: float,
        monthly_burns: float,
        vesting_schedule: Optional[list[float]] = None,
        label: str = "Base Case",
    ) -> None:
        """Initialize supply parameters.

        Args:
            name: Token name or identifier.
            total_supply: Maximum total supply of the token.
            circulating_supply: Current circulating supply.
            token_price: Current token price in USD.
            monthly_emissions: New tokens emitted per month (staking, LM).
            monthly_burns: Tokens burned per month.
            vesting_schedule: List of 12 monthly vesting unlock amounts.
                              If None, assumes zero vesting.
            label: Scenario label for display.
        """
        self.name = name
        self.total_supply = total_supply
        self.circulating_supply = circulating_supply
        self.token_price = token_price
        self.monthly_emissions = monthly_emissions
        self.monthly_burns = monthly_burns
        self.vesting_schedule = vesting_schedule or [0.0] * 12
        self.label = label

        # Pad vesting schedule to 12 months if shorter
        while len(self.vesting_schedule) < 12:
            self.vesting_schedule.append(0.0)


class MonthlyProjection:
    """Single month supply projection result."""

    def __init__(
        self,
        month: int,
        circulating: float,
        total_supply: float,
        emissions: float,
        vesting_unlock: float,
        burns: float,
        net_new: float,
        token_price: float,
    ) -> None:
        self.month = month
        self.circulating = circulating
        self.total_supply = total_supply
        self.emissions = emissions
        self.vesting_unlock = vesting_unlock
        self.burns = burns
        self.net_new = net_new
        self.token_price = token_price

    @property
    def circulating_pct(self) -> float:
        """Percentage of total supply in circulation."""
        return (self.circulating / self.total_supply * 100) if self.total_supply > 0 else 0

    @property
    def monthly_inflation_pct(self) -> float:
        """Monthly inflation rate as percentage."""
        prev = self.circulating - self.net_new
        return (self.net_new / prev * 100) if prev > 0 else 0

    @property
    def market_cap(self) -> float:
        """Estimated market cap."""
        return self.circulating * self.token_price

    @property
    def fdv(self) -> float:
        """Fully diluted valuation."""
        return self.total_supply * self.token_price

    @property
    def fdv_mcap_ratio(self) -> float:
        """FDV to market cap ratio."""
        return self.fdv / self.market_cap if self.market_cap > 0 else 0


# ── Projection Engine ──────────────────────────────────────────────
def project_supply(params: SupplyParams, months: int = 12) -> list[MonthlyProjection]:
    """Project token supply over specified months.

    Args:
        params: Supply parameters for the projection.
        months: Number of months to project (default 12).

    Returns:
        List of MonthlyProjection objects for each month.
    """
    projections: list[MonthlyProjection] = []
    circ = params.circulating_supply

    for m in range(months):
        vest = params.vesting_schedule[m] if m < len(params.vesting_schedule) else 0.0
        emissions = params.monthly_emissions
        burns = params.monthly_burns
        net_new = emissions + vest - burns

        # Cannot exceed total supply
        if circ + net_new > params.total_supply:
            net_new = params.total_supply - circ

        circ += net_new

        projections.append(
            MonthlyProjection(
                month=m + 1,
                circulating=circ,
                total_supply=params.total_supply,
                emissions=emissions,
                vesting_unlock=vest,
                burns=burns,
                net_new=net_new,
                token_price=params.token_price,
            )
        )

    return projections


def find_milestones(
    projections: list[MonthlyProjection],
    milestones: list[float] = [50.0, 75.0, 90.0, 100.0],
) -> list[dict]:
    """Find when circulating supply reaches key percentage milestones.

    Args:
        projections: List of monthly projections.
        milestones: Percentage milestones to track.

    Returns:
        List of milestone events with month and details.
    """
    results: list[dict] = []
    remaining = list(milestones)

    # Check starting point
    if projections:
        start_pct = (
            (projections[0].circulating - projections[0].net_new)
            / projections[0].total_supply
            * 100
        )
        # Remove milestones already passed
        remaining = [m for m in remaining if m > start_pct]

    for proj in projections:
        hit = [m for m in remaining if proj.circulating_pct >= m]
        for milestone in hit:
            results.append({
                "milestone_pct": milestone,
                "month": proj.month,
                "circulating": proj.circulating,
                "circulating_pct": proj.circulating_pct,
            })
            remaining.remove(milestone)

    # Report milestones not reached
    for m in remaining:
        results.append({
            "milestone_pct": m,
            "month": None,
            "circulating": None,
            "circulating_pct": None,
        })

    return results


def compare_scenarios(
    base: list[MonthlyProjection],
    alt: list[MonthlyProjection],
) -> list[dict]:
    """Compare two projection scenarios month by month.

    Args:
        base: Base case projections.
        alt: Alternative scenario projections.

    Returns:
        Monthly comparison with differences.
    """
    comparisons: list[dict] = []
    for b, a in zip(base, alt):
        comparisons.append({
            "month": b.month,
            "base_circulating_pct": round(b.circulating_pct, 2),
            "alt_circulating_pct": round(a.circulating_pct, 2),
            "diff_pct": round(a.circulating_pct - b.circulating_pct, 2),
            "base_inflation_pct": round(b.monthly_inflation_pct, 3),
            "alt_inflation_pct": round(a.monthly_inflation_pct, 3),
        })
    return comparisons


# ── Display ─────────────────────────────────────────────────────────
def format_num(n: float) -> str:
    """Format number with K/M/B suffix.

    Args:
        n: Number to format.

    Returns:
        Formatted string.
    """
    if abs(n) >= 1_000_000_000:
        return f"{n / 1_000_000_000:.2f}B"
    if abs(n) >= 1_000_000:
        return f"{n / 1_000_000:.2f}M"
    if abs(n) >= 1_000:
        return f"{n / 1_000:.1f}K"
    return f"{n:.0f}"


def print_projection_table(
    params: SupplyParams,
    projections: list[MonthlyProjection],
) -> None:
    """Print formatted projection table.

    Args:
        params: Supply parameters used.
        projections: Projection results.
    """
    print(f"\n{'=' * 80}")
    print(f"  SUPPLY PROJECTION: {params.name} — {params.label}")
    print(f"{'=' * 80}")
    print(f"  Total Supply:      {format_num(params.total_supply)}")
    print(f"  Starting Circ:     {format_num(params.circulating_supply)}")
    start_pct = params.circulating_supply / params.total_supply * 100
    print(f"  Starting Circ %:   {start_pct:.1f}%")
    print(f"  Token Price:       ${params.token_price:,.4f}")
    print(f"  Monthly Emissions: {format_num(params.monthly_emissions)}")
    print(f"  Monthly Burns:     {format_num(params.monthly_burns)}")
    total_vest = sum(params.vesting_schedule[:12])
    if total_vest > 0:
        print(f"  Total Vesting (12mo): {format_num(total_vest)}")

    # Table header
    print(f"\n  {'Mo':>3} | {'Circulating':>12} | {'Circ %':>7} | {'Net New':>10} "
          f"| {'Mo.Infl%':>8} | {'FDV/MCap':>8} | {'Est MCap':>12}")
    print(f"  {'-' * 3}-+-{'-' * 12}-+-{'-' * 7}-+-{'-' * 10}-"
          f"+-{'-' * 8}-+-{'-' * 8}-+-{'-' * 12}")

    for p in projections:
        mcap_str = f"${p.market_cap / 1e9:.2f}B" if p.market_cap >= 1e9 else f"${p.market_cap / 1e6:.1f}M"
        print(
            f"  {p.month:>3} | {format_num(p.circulating):>12} | "
            f"{p.circulating_pct:>6.1f}% | {format_num(p.net_new):>10} | "
            f"{p.monthly_inflation_pct:>7.2f}% | {p.fdv_mcap_ratio:>7.2f}x | "
            f"{mcap_str:>12}"
        )

    # Summary
    first = projections[0]
    last = projections[-1]
    total_new = sum(p.net_new for p in projections)
    total_inflation = (total_new / params.circulating_supply) * 100

    print(f"\n  12-Month Summary:")
    print(f"    Net new tokens:      {format_num(total_new)}")
    print(f"    Cumulative inflation: {total_inflation:.1f}%")
    print(f"    Circ % change:       {start_pct:.1f}% -> {last.circulating_pct:.1f}%")
    print(f"    FDV/MCap change:     {params.total_supply / params.circulating_supply:.2f}x -> {last.fdv_mcap_ratio:.2f}x")


def print_milestones(milestones: list[dict]) -> None:
    """Print milestone achievement summary.

    Args:
        milestones: List of milestone results.
    """
    print(f"\n  Supply Milestones:")
    for m in milestones:
        if m["month"] is not None:
            print(f"    {m['milestone_pct']:.0f}% circulating: reached in month {m['month']}")
        else:
            print(f"    {m['milestone_pct']:.0f}% circulating: not reached within projection period")


def print_scenario_comparison(
    base_params: SupplyParams,
    alt_params: SupplyParams,
    comparisons: list[dict],
) -> None:
    """Print side-by-side scenario comparison.

    Args:
        base_params: Base scenario parameters.
        alt_params: Alternative scenario parameters.
        comparisons: Monthly comparison data.
    """
    print(f"\n{'=' * 70}")
    print(f"  SCENARIO COMPARISON: {base_params.label} vs {alt_params.label}")
    print(f"{'=' * 70}")
    print(f"  Base burns/mo:  {format_num(base_params.monthly_burns)}")
    print(f"  Alt burns/mo:   {format_num(alt_params.monthly_burns)}")

    print(f"\n  {'Mo':>3} | {'Base Circ%':>10} | {'Alt Circ%':>10} | {'Diff':>7} "
          f"| {'Base Infl%':>10} | {'Alt Infl%':>10}")
    print(f"  {'-' * 3}-+-{'-' * 10}-+-{'-' * 10}-+-{'-' * 7}-+-{'-' * 10}-+-{'-' * 10}")

    for c in comparisons:
        print(
            f"  {c['month']:>3} | {c['base_circulating_pct']:>9.1f}% | "
            f"{c['alt_circulating_pct']:>9.1f}% | {c['diff_pct']:>+6.1f}% | "
            f"{c['base_inflation_pct']:>9.2f}% | {c['alt_inflation_pct']:>9.2f}%"
        )

    # Final difference
    last = comparisons[-1]
    print(f"\n  After 12 months:")
    print(f"    Base scenario: {last['base_circulating_pct']:.1f}% circulating")
    print(f"    Alt scenario:  {last['alt_circulating_pct']:.1f}% circulating")
    print(f"    Difference:    {last['diff_pct']:+.1f} percentage points")


# ── Demo Scenarios ──────────────────────────────────────────────────
def get_demo_params() -> SupplyParams:
    """Create demo parameters resembling a typical DeFi protocol token.

    Returns:
        SupplyParams with realistic example values.
    """
    # Vesting schedule: team cliff at month 6, then linear
    vesting = [
        0, 0, 0, 0, 0,          # months 1-5: no vesting
        25_000_000,              # month 6: cliff unlock (25M)
        5_000_000,               # months 7-12: linear vesting
        5_000_000,
        5_000_000,
        5_000_000,
        5_000_000,
        5_000_000,
    ]

    return SupplyParams(
        name="ExampleProtocol (EXMP)",
        total_supply=1_000_000_000,       # 1B total
        circulating_supply=300_000_000,   # 300M circulating (30%)
        token_price=2.50,
        monthly_emissions=8_000_000,      # 8M/mo from staking + LM
        monthly_burns=2_000_000,          # 2M/mo from fee burns
        vesting_schedule=vesting,
        label="Base Case (with burns)",
    )


def get_demo_no_burns() -> SupplyParams:
    """Create demo params without burn mechanism for comparison.

    Returns:
        SupplyParams identical to demo but with zero burns.
    """
    params = get_demo_params()
    params.monthly_burns = 0
    params.label = "No Burns"
    return params


# ── Interactive Mode ────────────────────────────────────────────────
def get_interactive_params() -> SupplyParams:
    """Prompt user for supply parameters interactively.

    Returns:
        SupplyParams from user input.
    """
    print("\n  Enter token supply parameters:")
    print("  (Press Enter for defaults shown in brackets)\n")

    def prompt_float(label: str, default: float) -> float:
        val = input(f"  {label} [{default:,.0f}]: ").strip()
        if not val:
            return default
        try:
            return float(val.replace(",", "").replace("_", ""))
        except ValueError:
            print(f"  Invalid number, using default: {default:,.0f}")
            return default

    name = input("  Token name [MyToken]: ").strip() or "MyToken"
    total = prompt_float("Total supply", 1_000_000_000)
    circ = prompt_float("Circulating supply", total * 0.3)
    price = prompt_float("Token price (USD)", 1.0)
    emissions = prompt_float("Monthly emissions", total * 0.008)
    burns = prompt_float("Monthly burns", total * 0.002)

    vest_input = input("  Include vesting schedule? (y/n) [n]: ").strip().lower()
    vesting: list[float] = [0.0] * 12
    if vest_input == "y":
        cliff_month = int(input("  Cliff month (1-12) [6]: ").strip() or "6")
        cliff_amount = prompt_float("Cliff unlock amount", total * 0.05)
        monthly_vest = prompt_float("Monthly vesting after cliff", total * 0.005)
        for m in range(12):
            if m + 1 == cliff_month:
                vesting[m] = cliff_amount
            elif m + 1 > cliff_month:
                vesting[m] = monthly_vest

    return SupplyParams(
        name=name,
        total_supply=total,
        circulating_supply=circ,
        token_price=price,
        monthly_emissions=emissions,
        monthly_burns=burns,
        vesting_schedule=vesting,
        label="Custom Scenario",
    )


# ── Main ────────────────────────────────────────────────────────────
def main() -> None:
    """Entry point for the supply modeler."""
    parser = argparse.ArgumentParser(
        description="Model token supply dynamics over 12 months"
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        default=False,
        help="Run with demo parameters (default if no other option specified)",
    )
    parser.add_argument(
        "--interactive",
        action="store_true",
        default=False,
        help="Interactively input supply parameters",
    )
    parser.add_argument(
        "--no-compare",
        action="store_true",
        default=False,
        help="Skip burn vs no-burn comparison",
    )
    args = parser.parse_args()

    if args.interactive:
        params = get_interactive_params()
    else:
        if not args.demo:
            print("No parameters specified, running demo mode.")
            print("Use --interactive for custom parameters.\n")
        params = get_demo_params()

    # Run base projection
    projections = project_supply(params)
    print_projection_table(params, projections)

    # Milestones
    milestones = find_milestones(projections)
    print_milestones(milestones)

    # Scenario comparison (burn vs no-burn)
    if not args.no_compare:
        if args.interactive:
            no_burn = SupplyParams(
                name=params.name,
                total_supply=params.total_supply,
                circulating_supply=params.circulating_supply,
                token_price=params.token_price,
                monthly_emissions=params.monthly_emissions,
                monthly_burns=0,
                vesting_schedule=list(params.vesting_schedule),
                label="No Burns",
            )
        else:
            no_burn = get_demo_no_burns()

        alt_projections = project_supply(no_burn)
        comparisons = compare_scenarios(projections, alt_projections)
        print_scenario_comparison(params, no_burn, comparisons)

    print(f"\n{'=' * 70}")
    print("  NOTE: Projections assume constant price and emission rates.")
    print("  Actual supply dynamics depend on governance, market conditions,")
    print("  and protocol changes. This is informational, not financial advice.")
    print(f"{'=' * 70}\n")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Tokenomics Analyzer — Fetch and analyze token supply metrics.

Fetches token data from CoinGecko's free API and calculates key tokenomics
metrics including dilution risk, supply dynamics, and basic valuation ratios.

Usage:
    python scripts/tokenomics_analyzer.py                  # uses --demo mode
    python scripts/tokenomics_analyzer.py --token solana
    python scripts/tokenomics_analyzer.py --token uniswap
    TOKEN_ID=raydium python scripts/tokenomics_analyzer.py

Dependencies:
    uv pip install httpx

Environment Variables:
    TOKEN_ID: CoinGecko token ID (optional, can use --token flag instead)
"""

import argparse
import sys
import time
from typing import Optional

try:
    import httpx
except ImportError:
    print("Missing dependency. Install with: uv pip install httpx")
    sys.exit(1)


# ── Configuration ───────────────────────────────────────────────────
COINGECKO_BASE = "https://api.coingecko.com/api/v3"
REQUEST_TIMEOUT = 30
RATE_LIMIT_WAIT = 65  # CoinGecko free tier: wait if rate-limited


# ── Data Models ─────────────────────────────────────────────────────
class TokenData:
    """Container for token data fetched from CoinGecko."""

    def __init__(self, raw: dict) -> None:
        self.name: str = raw.get("name", "Unknown")
        self.symbol: str = raw.get("symbol", "???").upper()
        self.coingecko_id: str = raw.get("id", "")

        md = raw.get("market_data", {})
        self.price: float = md.get("current_price", {}).get("usd", 0.0)
        self.market_cap: float = md.get("market_cap", {}).get("usd", 0.0)
        self.fdv: float = md.get("fully_diluted_valuation", {}).get("usd", 0.0)
        self.total_volume_24h: float = md.get("total_volume", {}).get("usd", 0.0)
        self.circulating_supply: float = md.get("circulating_supply") or 0.0
        self.total_supply: float = md.get("total_supply") or 0.0
        self.max_supply: Optional[float] = md.get("max_supply")

        self.price_change_24h: float = md.get("price_change_percentage_24h") or 0.0
        self.price_change_7d: float = md.get("price_change_percentage_7d") or 0.0
        self.price_change_30d: float = md.get("price_change_percentage_30d") or 0.0
        self.ath: float = md.get("ath", {}).get("usd", 0.0)
        self.ath_change_pct: float = md.get("ath_change_percentage", {}).get("usd", 0.0)


class TokenomicsReport:
    """Calculated tokenomics metrics and risk assessment."""

    def __init__(self, data: TokenData) -> None:
        self.data = data
        self.metrics = self._calculate_metrics()
        self.risks = self._assess_risks()
        self.valuation = self._basic_valuation()

    def _calculate_metrics(self) -> dict:
        """Calculate core tokenomics metrics."""
        d = self.data
        circulating_pct = (
            (d.circulating_supply / d.total_supply * 100) if d.total_supply > 0 else 0.0
        )
        fdv_mcap_ratio = d.fdv / d.market_cap if d.market_cap > 0 else 0.0
        locked_supply = d.total_supply - d.circulating_supply
        locked_value = locked_supply * d.price if d.price > 0 else 0.0

        return {
            "circulating_pct": round(circulating_pct, 2),
            "fdv_mcap_ratio": round(fdv_mcap_ratio, 2),
            "locked_supply": locked_supply,
            "locked_value_usd": locked_value,
            "has_max_supply": d.max_supply is not None,
            "max_supply_pct": (
                round(d.circulating_supply / d.max_supply * 100, 2)
                if d.max_supply and d.max_supply > 0
                else None
            ),
        }

    def _assess_risks(self) -> list[dict]:
        """Identify tokenomics risk factors."""
        risks = []
        m = self.metrics
        d = self.data

        # Dilution risk
        if m["fdv_mcap_ratio"] > 5.0:
            risks.append({
                "category": "Dilution",
                "severity": "HIGH",
                "detail": (
                    f"FDV/MCap ratio is {m['fdv_mcap_ratio']:.1f}x — "
                    f"significant future dilution ahead"
                ),
            })
        elif m["fdv_mcap_ratio"] > 3.0:
            risks.append({
                "category": "Dilution",
                "severity": "MEDIUM",
                "detail": (
                    f"FDV/MCap ratio is {m['fdv_mcap_ratio']:.1f}x — "
                    f"moderate dilution risk"
                ),
            })
        elif m["fdv_mcap_ratio"] > 1.5:
            risks.append({
                "category": "Dilution",
                "severity": "LOW",
                "detail": (
                    f"FDV/MCap ratio is {m['fdv_mcap_ratio']:.1f}x — "
                    f"some dilution expected but manageable"
                ),
            })

        # Low circulating supply
        if m["circulating_pct"] < 20:
            risks.append({
                "category": "Supply",
                "severity": "HIGH",
                "detail": (
                    f"Only {m['circulating_pct']:.1f}% of supply circulating — "
                    f"extreme dilution risk as tokens unlock"
                ),
            })
        elif m["circulating_pct"] < 50:
            risks.append({
                "category": "Supply",
                "severity": "MEDIUM",
                "detail": (
                    f"{m['circulating_pct']:.1f}% of supply circulating — "
                    f"majority of tokens still locked"
                ),
            })

        # Low volume relative to market cap
        if d.market_cap > 0 and d.total_volume_24h > 0:
            volume_mcap_ratio = d.total_volume_24h / d.market_cap
            if volume_mcap_ratio < 0.01:
                risks.append({
                    "category": "Liquidity",
                    "severity": "MEDIUM",
                    "detail": (
                        f"24h volume is only {volume_mcap_ratio:.2%} of market cap — "
                        f"low liquidity relative to valuation"
                    ),
                })

        # Distance from ATH
        if d.ath_change_pct < -90:
            risks.append({
                "category": "Price",
                "severity": "INFO",
                "detail": f"Token is {d.ath_change_pct:.1f}% from ATH — deeply discounted or declining",
            })

        # No max supply
        if not m["has_max_supply"]:
            risks.append({
                "category": "Inflation",
                "severity": "INFO",
                "detail": "No max supply cap — potential for unlimited inflation",
            })

        return risks

    def _basic_valuation(self) -> dict:
        """Calculate basic valuation metrics."""
        d = self.data
        metrics: dict = {}

        # FDV per volume (lower = more activity per dollar of valuation)
        if d.total_volume_24h > 0:
            fdv_volume = d.fdv / (d.total_volume_24h * 365)
            metrics["fdv_annualized_volume"] = round(fdv_volume, 2)
            if fdv_volume < 1:
                metrics["fdv_volume_assessment"] = "High activity relative to FDV"
            elif fdv_volume < 10:
                metrics["fdv_volume_assessment"] = "Moderate activity"
            else:
                metrics["fdv_volume_assessment"] = "Low activity relative to FDV"

        # Market cap per volume (daily turnover)
        if d.market_cap > 0 and d.total_volume_24h > 0:
            daily_turnover = d.total_volume_24h / d.market_cap * 100
            metrics["daily_turnover_pct"] = round(daily_turnover, 2)

        return metrics


# ── API Functions ───────────────────────────────────────────────────
def fetch_token_data(token_id: str) -> TokenData:
    """Fetch token data from CoinGecko free API.

    Args:
        token_id: CoinGecko token identifier (e.g., 'solana', 'uniswap').

    Returns:
        TokenData object with parsed market data.

    Raises:
        httpx.HTTPStatusError: On non-2xx response after retries.
        ValueError: If token not found.
    """
    url = f"{COINGECKO_BASE}/coins/{token_id}"
    params = {
        "localization": "false",
        "tickers": "false",
        "market_data": "true",
        "community_data": "false",
        "developer_data": "false",
        "sparkline": "false",
    }

    for attempt in range(3):
        try:
            resp = httpx.get(url, params=params, timeout=REQUEST_TIMEOUT)
            if resp.status_code == 429:
                print(f"  Rate limited, waiting {RATE_LIMIT_WAIT}s...")
                time.sleep(RATE_LIMIT_WAIT)
                continue
            if resp.status_code == 404:
                raise ValueError(
                    f"Token '{token_id}' not found on CoinGecko. "
                    f"Check the ID at https://www.coingecko.com/en/coins/{token_id}"
                )
            resp.raise_for_status()
            return TokenData(resp.json())
        except httpx.ConnectError:
            if attempt < 2:
                print(f"  Connection failed, retrying ({attempt + 1}/3)...")
                time.sleep(2)
            else:
                raise
    raise RuntimeError("Failed to fetch data after 3 attempts")


def search_token(query: str) -> Optional[str]:
    """Search for a token on CoinGecko and return its ID.

    Args:
        query: Search query (token name or symbol).

    Returns:
        CoinGecko token ID if found, None otherwise.
    """
    url = f"{COINGECKO_BASE}/search"
    try:
        resp = httpx.get(url, params={"query": query}, timeout=REQUEST_TIMEOUT)
        resp.raise_for_status()
        coins = resp.json().get("coins", [])
        if coins:
            return coins[0]["id"]
        return None
    except httpx.HTTPError:
        return None


# ── Demo Data ───────────────────────────────────────────────────────
def get_demo_data() -> TokenData:
    """Return demo data for illustration (based on a well-known L1 token).

    Returns:
        TokenData populated with example values.
    """
    demo_raw = {
        "id": "demo-token",
        "name": "DemoChain",
        "symbol": "DEMO",
        "market_data": {
            "current_price": {"usd": 150.0},
            "market_cap": {"usd": 65_000_000_000},
            "fully_diluted_valuation": {"usd": 89_000_000_000},
            "total_volume": {"usd": 2_500_000_000},
            "circulating_supply": 433_000_000,
            "total_supply": 590_000_000,
            "max_supply": None,
            "price_change_percentage_24h": -2.5,
            "price_change_percentage_7d": 5.1,
            "price_change_percentage_30d": -8.3,
            "ath": {"usd": 260.0},
            "ath_change_percentage": {"usd": -42.3},
        },
    }
    return TokenData(demo_raw)


# ── Display ─────────────────────────────────────────────────────────
def format_number(n: float, decimals: int = 2) -> str:
    """Format large numbers with K/M/B suffixes.

    Args:
        n: Number to format.
        decimals: Decimal places.

    Returns:
        Formatted string.
    """
    if abs(n) >= 1_000_000_000:
        return f"${n / 1_000_000_000:.{decimals}f}B"
    if abs(n) >= 1_000_000:
        return f"${n / 1_000_000:.{decimals}f}M"
    if abs(n) >= 1_000:
        return f"${n / 1_000:.{decimals}f}K"
    return f"${n:.{decimals}f}"


def format_supply(n: float) -> str:
    """Format supply numbers with M/B suffixes.

    Args:
        n: Supply number.

    Returns:
        Formatted string without dollar sign.
    """
    if abs(n) >= 1_000_000_000:
        return f"{n / 1_000_000_000:.2f}B"
    if abs(n) >= 1_000_000:
        return f"{n / 1_000_000:.2f}M"
    if abs(n) >= 1_000:
        return f"{n / 1_000:.2f}K"
    return f"{n:.0f}"


def print_report(report: TokenomicsReport) -> None:
    """Print formatted tokenomics report.

    Args:
        report: TokenomicsReport to display.
    """
    d = report.data
    m = report.metrics

    print("\n" + "=" * 65)
    print(f"  TOKENOMICS REPORT: {d.name} ({d.symbol})")
    print("=" * 65)

    # Price overview
    print(f"\n  Price:            ${d.price:,.4f}")
    print(f"  Market Cap:       {format_number(d.market_cap)}")
    print(f"  FDV:              {format_number(d.fdv)}")
    print(f"  24h Volume:       {format_number(d.total_volume_24h)}")

    # Price changes
    print(f"\n  Price Change:")
    print(f"    24h:  {d.price_change_24h:+.1f}%")
    print(f"    7d:   {d.price_change_7d:+.1f}%")
    print(f"    30d:  {d.price_change_30d:+.1f}%")
    print(f"    ATH:  {d.ath_change_pct:+.1f}% (ATH: ${d.ath:,.2f})")

    # Supply analysis
    print(f"\n  Supply:")
    print(f"    Circulating:    {format_supply(d.circulating_supply)}")
    print(f"    Total:          {format_supply(d.total_supply)}")
    if d.max_supply:
        print(f"    Max:            {format_supply(d.max_supply)}")
    else:
        print(f"    Max:            No cap")
    print(f"    Circulating %:  {m['circulating_pct']:.1f}%")
    print(f"    Locked Supply:  {format_supply(m['locked_supply'])}")
    print(f"    Locked Value:   {format_number(m['locked_value_usd'])}")

    # Dilution metrics
    print(f"\n  Dilution:")
    print(f"    FDV/MCap Ratio: {m['fdv_mcap_ratio']:.2f}x")
    if m["max_supply_pct"] is not None:
        print(f"    % of Max Minted: {m['max_supply_pct']:.1f}%")

    # Valuation
    if report.valuation:
        print(f"\n  Valuation:")
        if "fdv_annualized_volume" in report.valuation:
            print(f"    FDV/Ann.Volume: {report.valuation['fdv_annualized_volume']:.2f}x")
            print(f"    Assessment:     {report.valuation.get('fdv_volume_assessment', 'N/A')}")
        if "daily_turnover_pct" in report.valuation:
            print(f"    Daily Turnover: {report.valuation['daily_turnover_pct']:.2f}%")

    # Risk flags
    if report.risks:
        print(f"\n  Risk Flags:")
        for risk in report.risks:
            icon = {"HIGH": "[!]", "MEDIUM": "[*]", "LOW": "[-]", "INFO": "[i]"}.get(
                risk["severity"], "[?]"
            )
            print(f"    {icon} {risk['severity']:6s} | {risk['category']:10s} | {risk['detail']}")
    else:
        print(f"\n  Risk Flags: None identified")

    print("\n" + "=" * 65)
    print("  NOTE: This is informational analysis, not financial advice.")
    print("=" * 65 + "\n")


# ── Main ────────────────────────────────────────────────────────────
def main() -> None:
    """Entry point for the tokenomics analyzer."""
    parser = argparse.ArgumentParser(
        description="Analyze token supply dynamics and valuation metrics"
    )
    parser.add_argument(
        "--token", "-t",
        type=str,
        default=None,
        help="CoinGecko token ID (e.g., 'solana', 'uniswap', 'raydium')",
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Run with demo data (no API call needed)",
    )
    parser.add_argument(
        "--search", "-s",
        type=str,
        default=None,
        help="Search for a token by name or symbol",
    )
    args = parser.parse_args()

    import os
    token_id = args.token or os.getenv("TOKEN_ID", "")

    if args.demo or (not token_id and not args.search):
        print("Running in demo mode (use --token <id> for live data)")
        data = get_demo_data()
    elif args.search:
        print(f"Searching for '{args.search}'...")
        found_id = search_token(args.search)
        if not found_id:
            print(f"No token found for '{args.search}'")
            sys.exit(1)
        print(f"Found: {found_id}")
        print(f"Fetching data for '{found_id}'...")
        data = fetch_token_data(found_id)
    else:
        print(f"Fetching data for '{token_id}'...")
        try:
            data = fetch_token_data(token_id)
        except ValueError as e:
            print(f"Error: {e}")
            sys.exit(1)
        except httpx.HTTPError as e:
            print(f"HTTP error: {e}")
            sys.exit(1)

    report = TokenomicsReport(data)
    print_report(report)


if __name__ == "__main__":
    main()