Liquidity Analysis

#!/usr/bin/env python3
"""Analyze DEX liquidity depth for a Solana token.

Fetches pool data from DexScreener and Jupiter quotes to build a complete
liquidity profile: pool inventory, slippage curve, composite score, and
risk flags.

Usage:
    python scripts/analyze_liquidity.py                     # Demo mode (SOL/USDC)
    python scripts/analyze_liquidity.py <token_mint>        # Analyze specific token
    TOKEN_MINT=<address> python scripts/analyze_liquidity.py

Dependencies:
    uv pip install httpx

Environment Variables:
    TOKEN_MINT: Token mint address (optional, overridden by CLI arg)
"""

import math
import os
import sys
import time
from typing import Optional

import httpx

# ── Configuration ───────────────────────────────────────────────────
SOL_MINT = "So11111111111111111111111111111111111111112"
LAMPORTS = 1_000_000_000
SLIPPAGE_TEST_SIZES = [0.1, 0.5, 1.0, 5.0, 10.0, 25.0]
DEXSCREENER_BASE = "https://api.dexscreener.com"
JUPITER_QUOTE_URL = "https://api.jup.ag/quote/v1"

# Demo data for --demo mode or when API calls fail
DEMO_MINT = SOL_MINT  # SOL itself for demo
DEMO_POOLS = [
    {
        "pairAddress": "58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2",
        "dexId": "raydium",
        "baseToken": {"symbol": "SOL"},
        "quoteToken": {"symbol": "USDC"},
        "priceUsd": "145.50",
        "liquidity": {"usd": 12_500_000, "base": 43_000, "quote": 6_250_000},
        "volume": {"h24": 85_000_000},
        "pairCreatedAt": int((time.time() - 365 * 86400) * 1000),
        "labels": [],
    },
    {
        "pairAddress": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm",
        "dexId": "orca",
        "baseToken": {"symbol": "SOL"},
        "quoteToken": {"symbol": "USDC"},
        "priceUsd": "145.48",
        "liquidity": {"usd": 8_200_000, "base": 28_200, "quote": 4_100_000},
        "volume": {"h24": 42_000_000},
        "pairCreatedAt": int((time.time() - 300 * 86400) * 1000),
        "labels": ["concentrated"],
    },
    {
        "pairAddress": "FpCMFDFGYotvufJ7HrFHsWEiiQCGbkLCtwHiDnh7o28Q",
        "dexId": "meteora",
        "baseToken": {"symbol": "SOL"},
        "quoteToken": {"symbol": "USDC"},
        "priceUsd": "145.52",
        "liquidity": {"usd": 3_100_000, "base": 10_700, "quote": 1_550_000},
        "volume": {"h24": 15_000_000},
        "pairCreatedAt": int((time.time() - 120 * 86400) * 1000),
        "labels": ["dlmm"],
    },
]


# ── Data Fetching ──────────────────────────────────────────────────
def fetch_pools(mint: str) -> list[dict]:
    """Fetch all DEX pools for a token from DexScreener.

    Args:
        mint: Token mint address.

    Returns:
        List of pool/pair objects with liquidity data.
    """
    try:
        resp = httpx.get(
            f"{DEXSCREENER_BASE}/tokens/v1/solana/{mint}",
            timeout=15,
        )
        resp.raise_for_status()
        pairs = resp.json()
        if not isinstance(pairs, list):
            pairs = pairs.get("pairs", []) if isinstance(pairs, dict) else []
        return [p for p in pairs if p.get("liquidity", {}).get("usd", 0) > 0]
    except (httpx.HTTPError, ValueError) as e:
        print(f"  [warn] DexScreener fetch failed: {e}")
        return []


def fetch_jupiter_quote(
    token_mint: str, sol_amount: float, client: httpx.Client
) -> Optional[dict]:
    """Fetch a Jupiter quote for a specific trade size.

    Args:
        token_mint: Output token mint address.
        sol_amount: Amount of SOL to swap.
        client: Reusable httpx client.

    Returns:
        Quote response dict, or None on failure.
    """
    try:
        resp = client.get(
            JUPITER_QUOTE_URL,
            params={
                "inputMint": SOL_MINT,
                "outputMint": token_mint,
                "amount": str(int(sol_amount * LAMPORTS)),
                "slippageBps": 5000,
            },
            timeout=15,
        )
        if resp.status_code == 200:
            return resp.json()
    except (httpx.HTTPError, ValueError):
        pass
    return None


def build_slippage_curve(
    token_mint: str, sizes: Optional[list[float]] = None
) -> list[dict]:
    """Build empirical slippage curve via Jupiter quotes.

    Args:
        token_mint: Token to buy with SOL.
        sizes: SOL amounts to test.

    Returns:
        List of dicts with sol, tokens_out, slippage_bps.
    """
    if sizes is None:
        sizes = SLIPPAGE_TEST_SIZES

    results: list[dict] = []
    base_rate: Optional[float] = None

    with httpx.Client() as client:
        for sol in sizes:
            quote = fetch_jupiter_quote(token_mint, sol, client)
            if quote is None:
                continue
            out_amount = int(quote.get("outAmount", 0))
            if out_amount <= 0:
                continue
            rate = out_amount / sol
            if base_rate is None:
                base_rate = rate
            slippage_bps = int((1 - rate / base_rate) * 10000) if base_rate else 0
            results.append({
                "sol": sol,
                "tokens_out": out_amount,
                "slippage_bps": max(0, slippage_bps),
                "price_impact_pct": quote.get("priceImpactPct", "0"),
            })
            time.sleep(0.15)  # Respect rate limits

    return results


# ── Analysis Functions ─────────────────────────────────────────────
def pool_age_hours(pair_created_at_ms: int) -> float:
    """Calculate pool age in hours from creation timestamp.

    Args:
        pair_created_at_ms: Pool creation time in milliseconds.

    Returns:
        Age in hours, or 0 if timestamp is invalid.
    """
    if pair_created_at_ms <= 0:
        return 0.0
    return max(0.0, (time.time() * 1000 - pair_created_at_ms) / 3_600_000)


def compute_liquidity_score(
    total_liquidity_usd: float,
    pool_count: int,
    largest_pool_pct: float,
    oldest_pool_hours: float,
    max_slippage_bps_at_1sol: int,
) -> int:
    """Compute composite liquidity score from 0 (dangerous) to 100 (deep).

    Components:
        Depth (40%): log-scaled TVL from $1K (0) to $1M+ (40)
        Diversity (15%): more pools = more resilient, capped at 5 pools
        Concentration (15%): penalty if one pool dominates
        Age (15%): older pools are more reliable, full marks at 7 days
        Slippage (15%): lower slippage at 1 SOL = better

    Args:
        total_liquidity_usd: Total liquidity across all pools in USD.
        pool_count: Number of active pools.
        largest_pool_pct: Fraction of total liquidity in the largest pool (0-1).
        oldest_pool_hours: Age of the oldest pool in hours.
        max_slippage_bps_at_1sol: Slippage in bps for a 1 SOL trade.

    Returns:
        Score from 0 to 100.
    """
    # Depth: 0-40 points (log scale: $1K=0, $1M=40)
    if total_liquidity_usd <= 0:
        depth = 0
    else:
        depth = min(40, int(40 * math.log10(max(total_liquidity_usd, 1)) / 6))

    # Diversity: 0-15 points (3 pts per pool, max 5 pools)
    diversity = min(15, pool_count * 3)

    # Concentration: 0-15 points (penalize single-pool dominance)
    concentration = int(15 * (1 - largest_pool_pct))

    # Age: 0-15 points (7+ days = full marks)
    age = min(15, int(15 * min(oldest_pool_hours, 168) / 168))

    # Slippage: 0-15 points (0 bps = 15 pts, 150+ bps = 0 pts)
    slippage = max(0, 15 - max_slippage_bps_at_1sol // 10)

    return max(0, min(100, depth + diversity + concentration + age + slippage))


def detect_risk_flags(pools: list[dict]) -> list[str]:
    """Detect liquidity risk flags from pool data.

    Args:
        pools: List of DexScreener pool/pair objects.

    Returns:
        List of human-readable warning strings.
    """
    flags: list[str] = []

    if len(pools) == 0:
        flags.append("NO_POOLS: No active pools found")
        return flags

    if len(pools) == 1:
        flags.append("SINGLE_POOL: Only 1 pool exists — exit may be difficult")

    total_liq = sum(p.get("liquidity", {}).get("usd", 0) for p in pools)
    if total_liq < 10_000:
        flags.append(f"THIN_LIQUIDITY: Total TVL ${total_liq:,.0f} < $10,000")

    for p in pools:
        age_h = pool_age_hours(p.get("pairCreatedAt", 0))
        if 0 < age_h < 2:
            dex = p.get("dexId", "unknown")
            flags.append(f"NEW_POOL: {dex} pool is {age_h:.1f}h old")

    for p in pools:
        vol = p.get("volume", {}).get("h24", 0)
        liq = p.get("liquidity", {}).get("usd", 0)
        if liq > 0 and vol / liq > 10:
            dex = p.get("dexId", "unknown")
            flags.append(f"VOLUME_MISMATCH: {dex} 24h volume/TVL = {vol/liq:.1f}x (possible wash trading)")

    prices = [float(p.get("priceUsd", 0)) for p in pools if float(p.get("priceUsd", 0)) > 0]
    if len(prices) >= 2:
        deviation = (max(prices) - min(prices)) / min(prices)
        if deviation > 0.05:
            flags.append(f"PRICE_DEVIATION: {deviation:.1%} price difference across pools")

    return flags


def max_position_from_liquidity(
    total_liquidity_usd: float,
    max_slippage_pct: float = 1.0,
    trade_type: str = "swing",
) -> float:
    """Estimate maximum position size in USD based on available liquidity.

    Uses rule-of-thumb: for constant-product AMMs, trading X% of pool
    reserves produces approximately X% slippage.

    Args:
        total_liquidity_usd: Total liquidity across all pools.
        max_slippage_pct: Maximum acceptable slippage percentage.
        trade_type: One of "scalp", "swing", "position".

    Returns:
        Maximum position size in USD.
    """
    fractions = {"scalp": 0.01, "swing": 0.03, "position": 0.07}
    base_fraction = fractions.get(trade_type, 0.03)
    adjusted = base_fraction * (max_slippage_pct / 2.0)
    return total_liquidity_usd * adjusted


# ── Reporting ──────────────────────────────────────────────────────
def format_report(
    token_mint: str,
    pools: list[dict],
    slippage_curve: list[dict],
    score: int,
    flags: list[str],
    max_pos: float,
) -> str:
    """Format a complete liquidity analysis report.

    Args:
        token_mint: Token mint address.
        pools: Pool data from DexScreener.
        slippage_curve: Empirical slippage data from Jupiter.
        score: Composite liquidity score (0-100).
        flags: Risk flag strings.
        max_pos: Maximum recommended position size in USD.

    Returns:
        Formatted report string.
    """
    lines: list[str] = []
    lines.append("=" * 70)
    lines.append("LIQUIDITY ANALYSIS REPORT")
    lines.append("=" * 70)
    lines.append(f"Token: {token_mint}")
    lines.append(f"Pools: {len(pools)}")

    total_liq = sum(p.get("liquidity", {}).get("usd", 0) for p in pools)
    total_vol = sum(p.get("volume", {}).get("h24", 0) for p in pools)
    lines.append(f"Total Liquidity: ${total_liq:,.0f}")
    lines.append(f"Total 24h Volume: ${total_vol:,.0f}")
    lines.append("")

    # Pool breakdown
    lines.append("── Pool Breakdown " + "─" * 52)
    lines.append(f"  {'DEX':<12} {'Liquidity':>14} {'Volume 24h':>14} {'Age':>10} {'Price':>12}")
    lines.append("  " + "-" * 64)
    for p in sorted(pools, key=lambda x: x.get("liquidity", {}).get("usd", 0), reverse=True):
        dex = p.get("dexId", "?")[:11]
        liq = p.get("liquidity", {}).get("usd", 0)
        vol = p.get("volume", {}).get("h24", 0)
        age_h = pool_age_hours(p.get("pairCreatedAt", 0))
        price = p.get("priceUsd", "?")
        if age_h > 24:
            age_str = f"{age_h / 24:.0f}d"
        else:
            age_str = f"{age_h:.1f}h"
        lines.append(f"  {dex:<12} ${liq:>12,.0f} ${vol:>12,.0f} {age_str:>10} ${price:>10}")
    lines.append("")

    # Slippage curve
    if slippage_curve:
        lines.append("── Slippage Curve " + "─" * 52)
        lines.append(f"  {'SOL':>8} {'Tokens Out':>16} {'Slippage':>10} {'Impact':>10}")
        lines.append("  " + "-" * 46)
        for s in slippage_curve:
            sol_str = f"{s['sol']:.1f}"
            tokens = f"{s['tokens_out']:,}"
            slip = f"{s['slippage_bps']} bps"
            impact = f"{s.get('price_impact_pct', '?')}%"
            lines.append(f"  {sol_str:>8} {tokens:>16} {slip:>10} {impact:>10}")
        lines.append("")

    # Score and sizing
    lines.append("── Assessment " + "─" * 56)
    score_label = (
        "CRITICAL" if score < 20 else
        "POOR" if score < 40 else
        "FAIR" if score < 60 else
        "GOOD" if score < 80 else
        "EXCELLENT"
    )
    lines.append(f"  Liquidity Score: {score}/100 ({score_label})")
    lines.append(f"  Max Position (swing, 1% slip): ${max_pos:,.0f}")
    lines.append(f"  Max Position (scalp, 0.5% slip): ${max_position_from_liquidity(total_liq, 0.5, 'scalp'):,.0f}")
    lines.append("")

    # Risk flags
    if flags:
        lines.append("── Risk Flags " + "─" * 56)
        for f in flags:
            lines.append(f"  !! {f}")
        lines.append("")
    else:
        lines.append("── Risk Flags " + "─" * 56)
        lines.append("  No risk flags detected.")
        lines.append("")

    lines.append("=" * 70)
    lines.append("Note: This is informational analysis, not financial advice.")
    lines.append("Liquidity conditions change rapidly. Re-check before trading.")
    lines.append("=" * 70)

    return "\n".join(lines)


# ── Main ────────────────────────────────────────────────────────────
def main() -> None:
    """Run liquidity analysis for a token."""
    # Determine token mint
    if len(sys.argv) > 1:
        token_mint = sys.argv[1]
    else:
        token_mint = os.getenv("TOKEN_MINT", "")

    use_demo = not token_mint or token_mint == "--demo"

    if use_demo:
        print("[demo mode] Using hardcoded SOL/USDC pool data")
        print("Pass a token mint address as argument for live analysis.\n")
        token_mint = DEMO_MINT
        pools = DEMO_POOLS
        slippage_curve: list[dict] = [
            {"sol": 0.1, "tokens_out": 68_900, "slippage_bps": 0, "price_impact_pct": "0.00"},
            {"sol": 0.5, "tokens_out": 344_400, "slippage_bps": 1, "price_impact_pct": "0.01"},
            {"sol": 1.0, "tokens_out": 688_700, "slippage_bps": 2, "price_impact_pct": "0.02"},
            {"sol": 5.0, "tokens_out": 3_442_000, "slippage_bps": 5, "price_impact_pct": "0.05"},
            {"sol": 10.0, "tokens_out": 6_880_000, "slippage_bps": 8, "price_impact_pct": "0.08"},
            {"sol": 25.0, "tokens_out": 17_190_000, "slippage_bps": 15, "price_impact_pct": "0.15"},
        ]
    else:
        print(f"Fetching pools for {token_mint}...")
        pools = fetch_pools(token_mint)
        if not pools:
            print("No pools found. Token may not be listed or mint address may be incorrect.")
            sys.exit(1)
        print(f"Found {len(pools)} pool(s). Building slippage curve...")
        slippage_curve = build_slippage_curve(token_mint)

    # Compute metrics
    total_liq = sum(p.get("liquidity", {}).get("usd", 0) for p in pools)
    if total_liq > 0:
        largest_pool_liq = max(p.get("liquidity", {}).get("usd", 0) for p in pools)
        largest_pool_pct = largest_pool_liq / total_liq
    else:
        largest_pool_pct = 1.0

    oldest_hours = max(
        (pool_age_hours(p.get("pairCreatedAt", 0)) for p in pools),
        default=0.0,
    )

    slippage_at_1sol = 0
    for s in slippage_curve:
        if s["sol"] == 1.0:
            slippage_at_1sol = s["slippage_bps"]
            break

    score = compute_liquidity_score(
        total_liq, len(pools), largest_pool_pct, oldest_hours, slippage_at_1sol
    )
    flags = detect_risk_flags(pools)
    max_pos = max_position_from_liquidity(total_liq, max_slippage_pct=1.0, trade_type="swing")

    report = format_report(token_mint, pools, slippage_curve, score, flags, max_pos)
    print(report)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Compare DEX pools for a Solana token.

Fetches all pools from DexScreener, compares them by liquidity, volume,
age, and price, identifies the best pool for execution, and flags
suspicious pools.

Usage:
    python scripts/pool_comparison.py <token_mint>
    python scripts/pool_comparison.py                # Demo mode with BONK
    TOKEN_MINT=<address> python scripts/pool_comparison.py

Dependencies:
    uv pip install httpx

Environment Variables:
    TOKEN_MINT: Token mint address (optional, overridden by CLI arg)
"""

import os
import sys
import time
from typing import Optional

import httpx

# ── Configuration ───────────────────────────────────────────────────
DEXSCREENER_BASE = "https://api.dexscreener.com"

# BONK mint for demo mode
DEMO_MINT = "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"

DEMO_POOLS = [
    {
        "pairAddress": "8sLbNZoA1cfnvMJLPfp98ZR1Gm14nAkoTn4YzMNqDZkN",
        "dexId": "raydium",
        "baseToken": {"symbol": "BONK", "address": DEMO_MINT},
        "quoteToken": {"symbol": "SOL", "address": "So11111111111111111111111111111111111111112"},
        "priceUsd": "0.00002341",
        "liquidity": {"usd": 4_500_000, "base": 192_000_000_000, "quote": 15_500},
        "volume": {"h24": 12_000_000, "h6": 3_200_000, "h1": 450_000},
        "txns": {"h24": {"buys": 8500, "sells": 7200}},
        "pairCreatedAt": int((time.time() - 400 * 86400) * 1000),
        "labels": [],
    },
    {
        "pairAddress": "9dMXBpMXA1zMcbdv4PgFhoBLGsXgUEi6YkBhsK6kxPgA",
        "dexId": "orca",
        "baseToken": {"symbol": "BONK", "address": DEMO_MINT},
        "quoteToken": {"symbol": "SOL", "address": "So11111111111111111111111111111111111111112"},
        "priceUsd": "0.00002339",
        "liquidity": {"usd": 2_800_000, "base": 119_000_000_000, "quote": 9_650},
        "volume": {"h24": 7_500_000, "h6": 1_800_000, "h1": 280_000},
        "txns": {"h24": {"buys": 4200, "sells": 3900}},
        "pairCreatedAt": int((time.time() - 350 * 86400) * 1000),
        "labels": ["concentrated"],
    },
    {
        "pairAddress": "2KgMEJkL4XKqbFMjT2mFNc3VGHh7HQXR3HjfNfTS7Nfu",
        "dexId": "meteora",
        "baseToken": {"symbol": "BONK", "address": DEMO_MINT},
        "quoteToken": {"symbol": "SOL", "address": "So11111111111111111111111111111111111111112"},
        "priceUsd": "0.00002345",
        "liquidity": {"usd": 950_000, "base": 40_500_000_000, "quote": 3_270},
        "volume": {"h24": 3_200_000, "h6": 900_000, "h1": 120_000},
        "txns": {"h24": {"buys": 1800, "sells": 1500}},
        "pairCreatedAt": int((time.time() - 90 * 86400) * 1000),
        "labels": ["dlmm"],
    },
    {
        "pairAddress": "FakePoolForDemoSuspiciousActivity1234567890ab",
        "dexId": "raydium",
        "baseToken": {"symbol": "BONK", "address": DEMO_MINT},
        "quoteToken": {"symbol": "USDC", "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},
        "priceUsd": "0.00002290",
        "liquidity": {"usd": 5_000, "base": 214_000_000, "quote": 2_500},
        "volume": {"h24": 180_000, "h6": 45_000, "h1": 8_000},
        "txns": {"h24": {"buys": 120, "sells": 95}},
        "pairCreatedAt": int((time.time() - 0.5 * 86400) * 1000),
        "labels": [],
    },
]


# ── Data Fetching ──────────────────────────────────────────────────
def fetch_pools(mint: str) -> list[dict]:
    """Fetch all DEX pools for a token from DexScreener.

    Args:
        mint: Token mint address.

    Returns:
        List of pool/pair objects with liquidity > 0.
    """
    try:
        resp = httpx.get(
            f"{DEXSCREENER_BASE}/tokens/v1/solana/{mint}",
            timeout=15,
        )
        resp.raise_for_status()
        pairs = resp.json()
        if not isinstance(pairs, list):
            pairs = pairs.get("pairs", []) if isinstance(pairs, dict) else []
        return [p for p in pairs if p.get("liquidity", {}).get("usd", 0) > 0]
    except (httpx.HTTPError, ValueError) as e:
        print(f"  [warn] DexScreener fetch failed: {e}")
        return []


# ── Analysis Functions ─────────────────────────────────────────────
def pool_age_hours(pair_created_at_ms: int) -> float:
    """Calculate pool age in hours from creation timestamp.

    Args:
        pair_created_at_ms: Creation time in milliseconds.

    Returns:
        Age in hours.
    """
    if pair_created_at_ms <= 0:
        return 0.0
    return max(0.0, (time.time() * 1000 - pair_created_at_ms) / 3_600_000)


def format_age(hours: float) -> str:
    """Format age in hours to human-readable string.

    Args:
        hours: Age in hours.

    Returns:
        Formatted string like '3.5h', '14d', '6mo'.
    """
    if hours < 1:
        return f"{hours * 60:.0f}m"
    elif hours < 48:
        return f"{hours:.1f}h"
    elif hours < 24 * 90:
        return f"{hours / 24:.0f}d"
    else:
        return f"{hours / 24 / 30:.0f}mo"


def analyze_pool(pool: dict, all_pools: list[dict]) -> dict:
    """Analyze a single pool and compute metrics.

    Args:
        pool: DexScreener pair object.
        all_pools: All pools for context (price comparison).

    Returns:
        Dict with analysis metrics.
    """
    liq = pool.get("liquidity", {}).get("usd", 0)
    vol_24h = pool.get("volume", {}).get("h24", 0)
    age_h = pool_age_hours(pool.get("pairCreatedAt", 0))
    price = float(pool.get("priceUsd", 0))
    txns = pool.get("txns", {}).get("h24", {})
    buys = txns.get("buys", 0)
    sells = txns.get("sells", 0)
    total_txns = buys + sells

    # Volume/liquidity ratio (healthy: 1-5x, suspicious: >10x)
    vol_liq_ratio = vol_24h / liq if liq > 0 else 0

    # Buy/sell ratio (healthy: 0.4-0.6 buys, suspicious if very skewed)
    buy_ratio = buys / total_txns if total_txns > 0 else 0.5

    # Price deviation from median across all pools
    all_prices = [float(p.get("priceUsd", 0)) for p in all_pools if float(p.get("priceUsd", 0)) > 0]
    median_price = sorted(all_prices)[len(all_prices) // 2] if all_prices else price
    price_deviation_pct = abs(price - median_price) / median_price * 100 if median_price > 0 else 0

    return {
        "dex": pool.get("dexId", "unknown"),
        "pair_address": pool.get("pairAddress", ""),
        "base": pool.get("baseToken", {}).get("symbol", "?"),
        "quote": pool.get("quoteToken", {}).get("symbol", "?"),
        "price_usd": price,
        "liquidity_usd": liq,
        "volume_24h": vol_24h,
        "age_hours": age_h,
        "total_txns_24h": total_txns,
        "buy_ratio": buy_ratio,
        "vol_liq_ratio": vol_liq_ratio,
        "price_deviation_pct": price_deviation_pct,
        "labels": pool.get("labels", []),
    }


def flag_suspicious(analysis: dict) -> list[str]:
    """Flag suspicious characteristics for a pool.

    Args:
        analysis: Pool analysis dict from analyze_pool().

    Returns:
        List of warning strings.
    """
    flags: list[str] = []

    if analysis["age_hours"] < 2:
        flags.append("VERY_NEW: Pool less than 2 hours old")
    elif analysis["age_hours"] < 24:
        flags.append("NEW: Pool less than 24 hours old")

    if analysis["liquidity_usd"] < 5_000:
        flags.append(f"MICRO_LIQUIDITY: Only ${analysis['liquidity_usd']:,.0f}")
    elif analysis["liquidity_usd"] < 10_000:
        flags.append(f"LOW_LIQUIDITY: ${analysis['liquidity_usd']:,.0f}")

    if analysis["vol_liq_ratio"] > 10:
        flags.append(f"HIGH_VOL_RATIO: {analysis['vol_liq_ratio']:.1f}x volume/TVL")

    if analysis["price_deviation_pct"] > 5:
        flags.append(f"PRICE_OFF: {analysis['price_deviation_pct']:.1f}% from median")

    if analysis["buy_ratio"] > 0.85:
        flags.append(f"BUY_SKEWED: {analysis['buy_ratio']:.0%} buys (possible bot activity)")
    elif analysis["buy_ratio"] < 0.15:
        flags.append(f"SELL_SKEWED: {1 - analysis['buy_ratio']:.0%} sells (possible dump)")

    if analysis["total_txns_24h"] < 20:
        flags.append(f"LOW_ACTIVITY: Only {analysis['total_txns_24h']} txns in 24h")

    return flags


def rank_pools(analyses: list[dict]) -> list[dict]:
    """Rank pools by execution quality.

    Scoring: 50% liquidity rank + 30% volume rank + 20% age rank.
    Penalties for suspicious flags.

    Args:
        analyses: List of pool analysis dicts.

    Returns:
        Sorted list with added 'rank_score' field.
    """
    if not analyses:
        return []

    n = len(analyses)

    # Rank by each metric (higher = better)
    by_liq = sorted(range(n), key=lambda i: analyses[i]["liquidity_usd"])
    by_vol = sorted(range(n), key=lambda i: analyses[i]["volume_24h"])
    by_age = sorted(range(n), key=lambda i: analyses[i]["age_hours"])

    liq_rank = {idx: pos for pos, idx in enumerate(by_liq)}
    vol_rank = {idx: pos for pos, idx in enumerate(by_vol)}
    age_rank = {idx: pos for pos, idx in enumerate(by_age)}

    for i, a in enumerate(analyses):
        base_score = (
            0.50 * liq_rank[i] / max(n - 1, 1)
            + 0.30 * vol_rank[i] / max(n - 1, 1)
            + 0.20 * age_rank[i] / max(n - 1, 1)
        )
        # Penalty for suspicious flags
        flags = flag_suspicious(a)
        penalty = len(flags) * 0.1
        a["rank_score"] = max(0, base_score - penalty)
        a["flags"] = flags

    return sorted(analyses, key=lambda x: x["rank_score"], reverse=True)


# ── Reporting ──────────────────────────────────────────────────────
def format_comparison(token_mint: str, ranked: list[dict]) -> str:
    """Format pool comparison report.

    Args:
        token_mint: Token mint address.
        ranked: Ranked pool analyses.

    Returns:
        Formatted report string.
    """
    lines: list[str] = []
    lines.append("=" * 78)
    lines.append("POOL COMPARISON REPORT")
    lines.append("=" * 78)
    lines.append(f"Token: {token_mint}")
    lines.append(f"Pools Found: {len(ranked)}")

    total_liq = sum(a["liquidity_usd"] for a in ranked)
    total_vol = sum(a["volume_24h"] for a in ranked)
    lines.append(f"Total Liquidity: ${total_liq:,.0f}")
    lines.append(f"Total 24h Volume: ${total_vol:,.0f}")
    lines.append("")

    # Comparison table
    lines.append("── Pool Comparison " + "─" * 58)
    header = (
        f"  {'#':>2} {'DEX':<10} {'Pair':<10} {'Liquidity':>12} "
        f"{'Volume 24h':>12} {'Age':>6} {'Txns':>6} {'Score':>6}"
    )
    lines.append(header)
    lines.append("  " + "-" * 74)

    for i, a in enumerate(ranked, 1):
        pair = f"{a['base']}/{a['quote']}"[:9]
        age_str = format_age(a["age_hours"])
        lines.append(
            f"  {i:>2} {a['dex']:<10} {pair:<10} "
            f"${a['liquidity_usd']:>10,.0f} "
            f"${a['volume_24h']:>10,.0f} "
            f"{age_str:>6} "
            f"{a['total_txns_24h']:>5} "
            f"{a['rank_score']:>5.2f}"
        )
    lines.append("")

    # Best pool recommendation
    if ranked:
        best = ranked[0]
        lines.append("── Best Pool for Execution " + "─" * 50)
        lines.append(f"  DEX: {best['dex']}")
        lines.append(f"  Pair: {best['base']}/{best['quote']}")
        lines.append(f"  Address: {best['pair_address']}")
        lines.append(f"  Liquidity: ${best['liquidity_usd']:,.0f}")
        lines.append(f"  24h Volume: ${best['volume_24h']:,.0f}")
        lines.append(f"  Age: {format_age(best['age_hours'])}")
        pct = best["liquidity_usd"] / total_liq * 100 if total_liq > 0 else 0
        lines.append(f"  Share of Total Liquidity: {pct:.1f}%")
        lines.append("")

    # Suspicious pools
    suspicious = [a for a in ranked if a.get("flags")]
    if suspicious:
        lines.append("── Suspicious Pool Flags " + "─" * 52)
        for a in suspicious:
            lines.append(f"  {a['dex']} ({a['base']}/{a['quote']}):")
            for f in a["flags"]:
                lines.append(f"    !! {f}")
        lines.append("")

    # Price comparison
    prices = [a for a in ranked if a["price_usd"] > 0]
    if len(prices) >= 2:
        lines.append("── Price Comparison " + "─" * 57)
        for a in prices:
            lines.append(f"  {a['dex']:<10} {a['base']}/{a['quote']:<8} ${a['price_usd']:.10f}")
        min_p = min(a["price_usd"] for a in prices)
        max_p = max(a["price_usd"] for a in prices)
        spread = (max_p - min_p) / min_p * 100 if min_p > 0 else 0
        lines.append(f"  Price spread: {spread:.2f}%")
        if spread > 2:
            lines.append("  !! Significant price deviation — possible arbitrage or stale pool")
        lines.append("")

    lines.append("=" * 78)
    lines.append("Note: This is informational analysis, not financial advice.")
    lines.append("Pool conditions change rapidly. Re-check before trading.")
    lines.append("=" * 78)

    return "\n".join(lines)


# ── Main ────────────────────────────────────────────────────────────
def main() -> None:
    """Run pool comparison for a token."""
    if len(sys.argv) > 1:
        token_mint = sys.argv[1]
    else:
        token_mint = os.getenv("TOKEN_MINT", "")

    use_demo = not token_mint or token_mint == "--demo"

    if use_demo:
        print("[demo mode] Using hardcoded BONK pool data")
        print("Pass a token mint address as argument for live analysis.\n")
        token_mint = DEMO_MINT
        pools = DEMO_POOLS
    else:
        print(f"Fetching pools for {token_mint}...")
        pools = fetch_pools(token_mint)
        if not pools:
            print("No pools found. Token may not be listed or mint address may be incorrect.")
            sys.exit(1)
        print(f"Found {len(pools)} pool(s).\n")

    # Analyze each pool
    analyses = [analyze_pool(p, pools) for p in pools]

    # Rank and report
    ranked = rank_pools(analyses)
    report = format_comparison(token_mint, ranked)
    print(report)


if __name__ == "__main__":
    main()