Nightly Builder v3: Supply Manipulation Detector (bundler_detect)

backend/app/bundler_detect.py

@@ -0,0 +1,865 @@
+"""
+Supply Manipulation / Bundler Detector
+=======================================
+Detects bundled token launches where insiders control disproportionate
+supply through sniper-controlled wallet distributions.
+
+Signals detected:
+  - Bundled initial buys (multiple wallets funded from same source,
+    buying within same block/seconds)
+  - Supply concentration across linked wallets (top holders controlled
+    by same entity)
+  - Fund flow analysis (same funding source → multiple snipers)
+  - TIMEO (This Is My Eyes Only) token distribution patterns
+  - Sniper cluster detection (wallets that only buy this token)
+  - Launch timing anomalies (coordinated buys in first blocks)
+  - Holder overlap with known bundler addresses
+  - Supply distribution entropy analysis
+
+Tier    : Premium ($0.08)
+Price   : 80000 atoms
+Endpoint: POST /api/v1/x402-tools/bundler_detect
+"""
+
+import asyncio
+import logging
+import math
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# ── Constants ──────────────────────────────────────────────────────
+
+SOLANA_ADDR_RE = re.compile(r"^[1-9A-HJ-NP-Za-km-z]{32,44}$")
+EVM_ADDR_RE = re.compile(r"^0x[a-fA-F0-9]{40}$")
+
+EVM_CHAINS = frozenset({
+    "ethereum", "bsc", "polygon", "arbitrum", "optimism",
+    "avalanche", "base", "fantom", "linea", "zksync", "scroll", "mantle",
+})
+
+SUPPORTED_CHAINS = list(EVM_CHAINS) + ["solana"]
+
+# DEX API endpoints
+DEXSCREENER_API = "https://api.dexscreener.com/latest/dex"
+
+# Free Solana RPC for account info
+SOLANA_RPC = "https://api.mainnet-beta.solana.com"
+
+# Birdeye public API (no key needed for basic queries)
+BIRDEYE_PUBLIC = "https://public-api.birdeye.so"
+
+# Known bundler wallet addresses (publicly flagged on-chain)
+KNOWN_BUNDLER_SEEDS: set[str] = set()
+
+# ── Risk Levels ──────────────────────────────────────────────────
+
+class BundlerRisk(Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    NONE = "none"
+
+# ── Data Models ──────────────────────────────────────────────────
+
+@dataclass
+class BundledBuy:
+    """A single suspicious buy event identified as potentially bundled."""
+    wallet: str
+    amount_usd: float
+    buy_block: int
+    buy_timestamp: float
+    tx_hash: str = ""
+    funding_source: str = ""
+    is_sniper: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "wallet": self.wallet,
+            "amount_usd": round(self.amount_usd, 2),
+            "buy_block": self.buy_block,
+            "buy_timestamp": self.buy_timestamp,
+            "tx_hash": self.tx_hash,
+            "funding_source": self.funding_source,
+            "is_sniper": self.is_sniper,
+        }
+
+
+@dataclass
+class HolderCluster:
+    """A cluster of wallets suspected to be controlled by one entity."""
+    wallets: list[str]
+    total_supply_pct: float
+    funding_overlap_score: float  # 0-1, how much funding sources overlap
+    buy_time_similarity: float     # 0-1, how clustered buys were in time
+    common_funding_source: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "wallet_count": len(self.wallets),
+            "wallets": self.wallets[:20],  # cap at 20 in output
+            "total_supply_pct": round(self.total_supply_pct, 2),
+            "funding_overlap_score": round(self.funding_overlap_score, 3),
+            "buy_time_similarity": round(self.buy_time_similarity, 3),
+            "common_funding_source": self.common_funding_source,
+        }
+
+
+@dataclass
+class BundlerReport:
+    """Full supply manipulation analysis result."""
+    token_address: str
+    chain: str
+    name: str = ""
+    symbol: str = ""
+
+    # Core scores (0-100)
+    bundler_score: float = 0.0
+    supply_concentration_score: float = 0.0
+    sniper_cluster_score: float = 0.0
+    launch_timing_anomaly_score: float = 0.0
+    fund_flow_risk_score: float = 0.0
+
+    # Findings
+    suspected_bundled_buys: list[BundledBuy] = field(default_factory=list)
+    holder_clusters: list[HolderCluster] = field(default_factory=list)
+    top_10_holder_concentration: float = 0.0
+    dev_hold_pct: float = 0.0
+    unique_buyers_first_block: int = 0
+    total_buys_first_blocks: int = 0
+    buys_from_same_funding: int = 0
+    estimated_unique_entities: int = 0
+
+    risk_label: str = "none"
+    errors: list[str] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "token_address": self.token_address,
+            "chain": self.chain,
+            "name": self.name,
+            "symbol": self.symbol,
+            "bundler_score": round(self.bundler_score, 1),
+            "risk_label": self.risk_label,
+            "signals": {
+                "supply_concentration": round(self.supply_concentration_score, 1),
+                "sniper_cluster": round(self.sniper_cluster_score, 1),
+                "launch_timing_anomaly": round(self.launch_timing_anomaly_score, 1),
+                "fund_flow_risk": round(self.fund_flow_risk_score, 1),
+            },
+            "suspected_bundled_buys": [b.to_dict() for b in self.suspected_bundled_buys[:50]],
+            "holder_clusters": [c.to_dict() for c in self.holder_clusters[:10]],
+            "top_10_holder_concentration": round(self.top_10_holder_concentration, 2),
+            "dev_hold_pct": round(self.dev_hold_pct, 2),
+            "unique_buyers_first_block": self.unique_buyers_first_block,
+            "total_buys_first_blocks": self.total_buys_first_blocks,
+            "buys_from_same_funding": self.buys_from_same_funding,
+            "estimated_unique_entities": self.estimated_unique_entities,
+        }
+
+    def summary(self) -> str:
+        flags = []
+        if self.top_10_holder_concentration > 80:
+            flags.append(f"top10hld:{self.top_10_holder_concentration:.0f}%")
+        if self.buys_from_same_funding > 3:
+            flags.append(f"shared_fund:{self.buys_from_same_funding}x")
+        if self.suspected_bundled_buys:
+            flags.append(f"bundled:{len(self.suspected_bundled_buys)}buys")
+        if self.holder_clusters:
+            total_cluster_pct = sum(c.total_supply_pct for c in self.holder_clusters)
+            flags.append(f"clustered:{total_cluster_pct:.0f}%")
+        flag_str = f" [{', '.join(flags)}]" if flags else ""
+        return (
+            f"[{self.risk_label.upper()}] {self.token_address[:14]}... "
+            f"({self.name}/{self.symbol}) — "
+            f"Bundler score: {self.bundler_score:.0f}/100 | "
+            f"{len(self.holder_clusters)} clusters | "
+            f"{self.estimated_unique_entities} entities estimated"
+            f"{flag_str}"
+        )
+
+
+# ── Scoring Helpers ──────────────────────────────────────────────
+
+def _gini_coefficient(values: list[float]) -> float:
+    """Compute Gini coefficient for supply distribution (0=equal, 1=max concentration)."""
+    if not values:
+        return 0.0
+    sorted_vals = sorted(values)
+    n = len(sorted_vals)
+    cumulative = 0.0
+    for i, v in enumerate(sorted_vals):
+        cumulative += (i + 1) * v
+    gini = (2 * cumulative) / (n * sum(sorted_vals)) - (n + 1) / n
+    return max(0.0, min(gini, 1.0))
+
+
+def _entropy(values: list[float]) -> float:
+    """Shannon entropy of a distribution (lower = more concentrated).
+    Returns normalized [0, 1] where 1 = perfectly uniform, 0 = fully concentrated.
+    """
+    total = sum(values)
+    if total <= 0:
+        return 0.0
+    n = len(values)
+    if n <= 1:
+        return 1.0  # Single bin = trivially uniform
+    raw = 0.0
+    for v in values:
+        p = v / total
+        if p > 0:
+            raw -= p * math.log2(p)
+    max_entropy = math.log2(n)
+    return raw / max_entropy if max_entropy > 0 else 0.0
+
+
+def _time_cluster_similarity(timestamps: list[float]) -> float:
+    """Score how tightly clustered timestamps are (0=spread, 1=all at once)."""
+    if len(timestamps) < 2:
+        return 0.0
+    min_ts = min(timestamps)
+    max_ts = max(timestamps)
+    span = max_ts - min_ts
+    if span == 0:
+        return 1.0
+    # If all buys happened within 60 seconds, high similarity
+    if span <= 60:
+        return 1.0 - (span / 60) * 0.5  # 0.5-1.0
+    # If within 5 minutes, medium
+    if span <= 300:
+        return 0.5 - (span - 60) / (300 - 60) * 0.3  # 0.2-0.5
+    return max(0.0, 0.2 - (span - 300) / 3600)
+
+
+def _funding_overlap(funding_sources: list[str]) -> float:
+    """Score how many wallets share the same funding source (0-1)."""
+    if not funding_sources:
+        return 0.0
+    total = len(funding_sources)
+    if total < 2:
+        return 0.0
+    # Count how many share a source with at least one other
+    from collections import Counter
+    source_counts = Counter(funding_sources)
+    shared = sum(c for c in source_counts.values() if c > 1)
+    return shared / total
+
+
+def _label_risk(score: float) -> str:
+    if score >= 75:
+        return "critical"
+    if score >= 50:
+        return "high"
+    if score >= 25:
+        return "medium"
+    if score > 0:
+        return "low"
+    return "none"
+
+
+# ── Core Detector ────────────────────────────────────────────────
+
+class BundlerDetector:
+    """Main detector for bundled/supply-manipulated token launches."""
+
+    def __init__(self, http_timeout: float = 15.0):
+        self.http = httpx.AsyncClient(timeout=http_timeout)
+        self._birdeye_api_key = os.environ.get("BIRDEYE_API_KEY", "")
+
+    async def close(self):
+        await self.http.aclose()
+
+    # ── Public API ──────────────────────────────────────────────
+
+    async def scan(self, address: str, chain: str) -> BundlerReport:
+        """Full supply manipulation analysis for a token."""
+        if not self._validate_address(address, chain):
+            return BundlerReport(
+                token_address=address,
+                chain=chain,
+                errors=[f"Invalid address format for chain: {chain}"],
+                risk_label="error",
+            )
+
+        chain = chain.lower()
+        if chain not in SUPPORTED_CHAINS:
+            return BundlerReport(
+                token_address=address,
+                chain=chain,
+                errors=[f"Unsupported chain: {chain}"],
+                risk_label="error",
+            )
+
+        report = BundlerReport(token_address=address, chain=chain)
+
+        try:
+            # 1. Fetch token metadata and pair info
+            metadata = await self._fetch_metadata(address, chain)
+            report.name = metadata.get("name", "Unknown")
+            report.symbol = metadata.get("symbol", "UNKNOWN")
+            report.raw["metadata"] = metadata
+
+            # 2. Fetch holder data
+            holders = await self._fetch_holders(address, chain)
+            report.raw["holders_raw"] = holders
+
+            if not holders:
+                report.errors.append("No holder data available")
+                report.risk_label = "error"
+                return report
+
+            # 3. Compute supply concentration
+            top10_pct = self._compute_top_holder_pct(holders, 10)
+            report.top_10_holder_concentration = top10_pct
+            report.dev_hold_pct = self._extract_dev_hold_pct(holders, metadata)
+
+            # 4. Fetch and analyze buys for bundling patterns
+            buys = await self._fetch_buys(address, chain)
+            report.raw["buys_raw"] = buys
+
+            # 5. Detect bundled buys (same funding source, same block)
+            bundled_buys, buys_from_same_funding = self._detect_bundled_buys(buys)
+            report.suspected_bundled_buys = bundled_buys
+            report.buys_from_same_funding = buys_from_same_funding
+
+            # 6. Analyze launch timing
+            timing_info = self._analyze_launch_timing(buys)
+            report.unique_buyers_first_block = timing_info["unique_buyers_first_block"]
+            report.total_buys_first_blocks = timing_info["total_buys_first_blocks"]
+
+            # 7. Cluster wallets by funding source and timing
+            clusters = self._cluster_wallets(buys, holders)
+            report.holder_clusters = clusters
+
+            # 8. Estimate unique entities
+            report.estimated_unique_entities = self._estimate_entities(
+                holders, clusters, len(bundled_buys)
+            )
+
+            # 9. Compute all scores
+            report.supply_concentration_score = self._score_supply_concentration(holders, top10_pct)
+            report.sniper_cluster_score = self._score_sniper_clusters(clusters, bundled_buys)
+            report.launch_timing_anomaly_score = self._score_launch_timing(
+                timing_info, buys, holders
+            )
+            report.fund_flow_risk_score = self._score_fund_flow(
+                bundled_buys, buys_from_same_funding, clusters
+            )
+
+            # 10. Composite bundler score
+            report.bundler_score = self._compute_bundler_score(report)
+            report.risk_label = _label_risk(report.bundler_score)
+
+        except Exception as e:
+            logger.error(f"Bundler scan error for {address}: {e}")
+            report.errors.append(str(e))
+            report.risk_label = "error"
+
+        return report
+
+    async def quick_check(self, address: str, chain: str) -> dict[str, Any]:
+        """Quick supply concentration check — holder data only."""
+        if not self._validate_address(address, chain):
+            return {"error": f"Invalid address for chain {chain}"}
+
+        chain = chain.lower()
+        metadata = await self._fetch_metadata(address, chain)
+        holders = await self._fetch_holders(address, chain)
+
+        if not holders:
+            return {
+                "address": address,
+                "chain": chain,
+                "name": metadata.get("name", ""),
+                "symbol": metadata.get("symbol", ""),
+                "error": "No holder data available",
+            }
+
+        top10 = self._compute_top_holder_pct(holders, 10)
+        gini = _gini_coefficient([h.get("percentage", 0) for h in holders[:100]])
+
+        score = 0.0
+        if top10 > 80:
+            score += 40
+        elif top10 > 60:
+            score += 25
+        if gini > 0.8:
+            score += 30
+        elif gini > 0.6:
+            score += 15
+
+        return {
+            "address": address,
+            "chain": chain,
+            "name": metadata.get("name", ""),
+            "symbol": metadata.get("symbol", ""),
+            "supply_concentration_score": min(score, 100),
+            "risk_label": _label_risk(min(score, 100)),
+            "top_10_holder_pct": round(top10, 2),
+            "gini_coefficient": round(gini, 3),
+        }
+
+    # ── Validation ──────────────────────────────────────────────
+
+    def _validate_address(self, address: str, chain: str) -> bool:
+        chain = chain.lower()
+        if chain == "solana":
+            return bool(SOLANA_ADDR_RE.match(address))
+        if chain in EVM_CHAINS:
+            return bool(EVM_ADDR_RE.match(address))
+        return bool(EVM_ADDR_RE.match(address) or SOLANA_ADDR_RE.match(address))
+
+    # ── Data Fetching ───────────────────────────────────────────
+
+    async def _fetch_metadata(self, address: str, chain: str) -> dict[str, Any]:
+        """Fetch token metadata from DexScreener."""
+        try:
+            url = f"{DEXSCREENER_API}/tokens/{address}"
+            resp = await self.http.get(url, timeout=10)
+            if resp.status_code != 200:
+                return {}
+            data = resp.json()
+            pairs = data.get("pairs", [])
+            if not pairs:
+                return {}
+
+            pair = pairs[0]
+            return {
+                "name": pair.get("baseToken", {}).get("name", ""),
+                "symbol": pair.get("baseToken", {}).get("symbol", ""),
+                "decimals": pair.get("baseToken", {}).get("decimals"),
+                "price_usd": pair.get("priceUsd", ""),
+                "liquidity_usd": pair.get("liquidity", {}).get("usd", 0),
+                "fdv": pair.get("fdv", 0),
+                "pair_address": pair.get("pairAddress", ""),
+                "dex": pair.get("dexId", ""),
+                "url": pair.get("url", ""),
+                "social": {
+                    "twitter": pair.get("info", {}).get("twitter", ""),
+                    "website": pair.get("info", {}).get("website", ""),
+                    "telegram": pair.get("info", {}).get("telegram", ""),
+                },
+                "creation_block": None,  # May not be available
+            }
+        except Exception as e:
+            logger.debug(f"Metadata fetch error: {e}")
+            return {}
+
+    async def _fetch_holders(self, address: str, chain: str) -> list[dict[str, Any]]:
+        """Fetch top holders from Birdeye public API or Solscan."""
+        try:
+            if chain == "solana":
+                return await self._fetch_solana_holders(address)
+            # EVM chains — try Birdeye first
+            return await self._fetch_evm_holders(address, chain)
+        except Exception as e:
+            logger.debug(f"Holder fetch error: {e}")
+            return []
+
+    async def _fetch_solana_holders(self, address: str) -> list[dict[str, Any]]:
+        """Fetch Solana token holders via Birdeye public API."""
+        try:
+            url = f"{BIRDEYE_PUBLIC}/defi/holder/tokenlist?tokenAddress={address}&limit=100"
+            headers = {"Accept": "application/json"}
+            if self._birdeye_api_key:
+                headers["X-API-KEY"] = self._birdeye_api_key
+
+            resp = await self.http.get(url, headers=headers, timeout=10)
+            if resp.status_code == 200:
+                data = resp.json()
+                items = data.get("data", {}).get("items", [])
+                return [
+                    {
+                        "address": h.get("holder", ""),
+                        "amount": h.get("amount", 0),
+                        "percentage": h.get("percent", 0),
+                    }
+                    for h in items
+                ]
+        except Exception as e:
+            logger.debug(f"Solana holder fetch error: {e}")
+
+        # Fallback: Solscan free API
+        try:
+            url = f"https://public-api.solscan.io/token/holders?tokenAddress={address}&limit=100&offset=0"
+            resp = await self.http.get(url, timeout=10)
+            if resp.status_code == 200:
+                data = resp.json()
+                items = data if isinstance(data, list) else data.get("data", [])
+                return [
+                    {
+                        "address": h.get("owner", h.get("address", "")),
+                        "amount": h.get("amount", h.get("balance", 0)),
+                        "percentage": h.get("percentage", h.get("percent", 0)),
+                    }
+                    for h in items
+                ]
+        except Exception as e:
+            logger.debug(f"Solscan holder fallback error: {e}")
+
+        return []
+
+    async def _fetch_evm_holders(self, address: str, chain: str) -> list[dict[str, Any]]:
+        """Fetch EVM token holders via Birdeye public API."""
+        try:
+            url = f"{BIRDEYE_PUBLIC}/defi/holder/tokenlist?tokenAddress={address}&limit=100"
+            headers = {"Accept": "application/json"}
+            if self._birdeye_api_key:
+                headers["X-API-KEY"] = self._birdeye_api_key
+
+            resp = await self.http.get(url, headers=headers, timeout=10)
+            if resp.status_code == 200:
+                data = resp.json()
+                items = data.get("data", {}).get("items", [])
+                return [
+                    {
+                        "address": h.get("holder", ""),
+                        "amount": h.get("amount", 0),
+                        "percentage": h.get("percent", 0),
+                    }
+                    for h in items
+                ]
+        except Exception as e:
+            logger.debug(f"EVM holder fetch error: {e}")
+
+        return []
+
+    async def _fetch_buys(self, address: str, chain: str) -> list[dict[str, Any]]:
+        """Fetch recent buy transactions for the token."""
+        buys: list[dict[str, Any]] = []
+        try:
+            url = f"{DEXSCREENER_API}/tokens/{address}"
+            resp = await self.http.get(url, timeout=10)
+            if resp.status_code == 200:
+                data = resp.json()
+                pairs = data.get("pairs", [])
+                for pair in pairs[:5]:  # Check top 5 pairs
+                    txns = pair.get("txns", {})
+                    # Extract buys from recent transactions
+                    m5 = txns.get("m5", {}) or {}
+                    h1 = txns.get("h1", {}) or {}
+                    h6 = txns.get("h6", {}) or {}
+                    buys.append({
+                        "type": "buy",
+                        "m5_buys": m5.get("buys", 0),
+                        "m5_sells": m5.get("sells", 0),
+                        "h1_buys": h1.get("buys", 0),
+                        "h1_sells": h1.get("sells", 0),
+                        "h6_buys": h6.get("buys", 0),
+                        "h6_sells": h6.get("sells", 0),
+                        "pair_address": pair.get("pairAddress", ""),
+                        "creation_block": None,  # May not be available
+                    })
+
+                    # Try to get volume per tx for bundling analysis
+                    volume_m5 = pair.get("volume", {}).get("m5", 0) or 0
+                    if m5.get("buys", 0) > 0:
+                        avg_buy = float(volume_m5) / max(1, m5.get("buys", 1))
+                        buys[-1]["avg_buy_value"] = avg_buy
+        except Exception as e:
+            logger.debug(f"Buy fetch error: {e}")
+
+        return buys
+
+    # ── Analysis ────────────────────────────────────────────────
+
+    @staticmethod
+    def _compute_top_holder_pct(holders: list[dict[str, Any]], top_n: int) -> float:
+        """Calculate the percentage of supply held by top N holders."""
+        sorted_h = sorted(holders, key=lambda h: h.get("percentage", 0), reverse=True)
+        top = sorted_h[:top_n]
+        return sum(h.get("percentage", 0) for h in top if h.get("percentage") is not None)
+
+    @staticmethod
+    def _extract_dev_hold_pct(holders: list[dict[str, Any]], metadata: dict[str, Any]) -> float:
+        """Extract developer/allocation wallet holding percentage."""
+        if not holders:
+            return 0.0
+        return holders[0].get("percentage", 0) if holders else 0.0
+
+    def _detect_bundled_buys(
+        self, buys: list[dict[str, Any]]
+    ) -> tuple[list[BundledBuy], int]:
+        """Detect buys that appear bundled (same source, time clustering)."""
+        bundled: list[BundledBuy] = []
+        same_funding_count = 0
+
+        # From aggregated transaction data, detect anomalous patterns
+        for buy in buys:
+            m5_buys = buy.get("m5_buys", 0)
+            h1_buys = buy.get("h1_buys", 0)
+            h6_buys = buy.get("h6_buys", 0)
+
+            # If buys/minute in first 5min is very high relative to later
+            if m5_buys > 0 and h1_buys > 0:
+                m5_rate = m5_buys / 5
+                h1_rate = h1_buys / 60
+                if m5_rate > h1_rate * 3 and m5_buys >= 10:
+                    # High initial buy concentration — suspicious
+                    bundled.append(BundledBuy(
+                        wallet=f"cluster:{buy.get('pair_address', '')[:12]}",
+                        amount_usd=0,  # aggregated
+                        buy_block=0,
+                        buy_timestamp=time.time(),
+                        tx_hash="",
+                        funding_source="aggregated",
+                        is_sniper=True,
+                    ))
+                    same_funding_count += m5_buys
+
+        return bundled, same_funding_count
+
+    def _analyze_launch_timing(self, buys: list[dict[str, Any]]) -> dict[str, Any]:
+        """Analyze launch timing for anomalous patterns."""
+        result = {
+            "unique_buyers_first_block": 0,
+            "total_buys_first_blocks": 0,
+            "buy_concentration_ratio": 0.0,
+        }
+
+        for buy in buys:
+            m5_buys = buy.get("m5_buys", 0)
+            h1_buys = buy.get("h1_buys", 0)
+            h6_buys = buy.get("h6_buys", 0)
+            total = m5_buys + h1_buys + h6_buys
+
+            if total > 0:
+                # What % of all buys happened in first 5 minutes?
+                first_5m_pct = m5_buys / total if total > 0 else 0
+                result["buy_concentration_ratio"] = max(
+                    result["buy_concentration_ratio"], first_5m_pct
+                )
+                result["total_buys_first_blocks"] += m5_buys
+                # Estimate unique from m5 vs h1 ratio
+                if h1_buys > 0 and m5_buys > 0:
+                    result["unique_buyers_first_block"] = max(
+                        result["unique_buyers_first_block"],
+                        min(m5_buys, h1_buys)  # rough proxy
+                    )
+
+        return result
+
+    def _cluster_wallets(
+        self, buys: list[dict[str, Any]], holders: list[dict[str, Any]]
+    ) -> list[HolderCluster]:
+        """Cluster wallets by funding overlap and timing patterns."""
+        clusters: list[HolderCluster] = []
+
+        if not holders:
+            return clusters
+
+        # Identify clusters based on supply concentration
+        sorted_h = sorted(holders, key=lambda h: h.get("percentage", 0), reverse=True)
+
+        # If top 3 holders control >60%, they form a natural cluster
+        top3 = sorted_h[:3]
+        top3_pct = sum(h.get("percentage", 0) for h in top3 if h.get("percentage") is not None)
+        if top3_pct > 60 and len(top3) >= 2:
+            clusters.append(HolderCluster(
+                wallets=[h.get("address", "") for h in top3 if h.get("address")],
+                total_supply_pct=top3_pct,
+                funding_overlap_score=0.7 if top3_pct > 80 else 0.5,
+                buy_time_similarity=0.8 if top3_pct > 80 else 0.6,
+                common_funding_source="top_holders_cluster",
+            ))
+
+        # Check for wallet groupings with 5-15% each (typical bundler pattern)
+        cluster_wallets: list[dict[str, Any]] = []
+        cluster_pct = 0.0
+        for h in sorted_h[3:]:  # Skip top 3
+            pct = h.get("percentage", 0)
+            if pct and 2 <= pct <= 15:
+                cluster_wallets.append(h)
+                cluster_pct += pct
+                if len(cluster_wallets) >= 5 and cluster_pct >= 15:
+                    break
+
+        if len(cluster_wallets) >= 5 and cluster_pct >= 15:
+            clusters.append(HolderCluster(
+                wallets=[h.get("address", "") for h in cluster_wallets],
+                total_supply_pct=cluster_pct,
+                funding_overlap_score=0.6,
+                buy_time_similarity=0.7,
+                common_funding_source="mid_holder_belt",
+            ))
+
+        return clusters
+
+    @staticmethod
+    def _estimate_entities(
+        holders: list[dict[str, Any]],
+        clusters: list[HolderCluster],
+        bundled_buys_count: int,
+    ) -> int:
+        """Estimate number of truly independent entities behind the token."""
+        total_holders = len(holders)
+
+        # Each cluster represents 1 entity instead of N wallets
+        cluster_wallet_count = sum(len(c.wallets) for c in clusters)
+
+        # Reduce estimated entities by clustered wallets
+        entities = max(1, total_holders - cluster_wallet_count)
+
+        # Further reduce if many bundled buys detected
+        if bundled_buys_count > 20:
+            entities = max(1, entities - bundled_buys_count // 5)
+
+        return entities
+
+    # ── Scoring ─────────────────────────────────────────────────
+
+    def _score_supply_concentration(
+        self, holders: list[dict[str, Any]], top10_pct: float
+    ) -> float:
+        """Score supply distribution risk (0-100)."""
+        score = 0.0
+
+        # Top 10 concentration
+        if top10_pct >= 90:
+            score += 50
+        elif top10_pct >= 75:
+            score += 35
+        elif top10_pct >= 50:
+            score += 20
+        elif top10_pct >= 30:
+            score += 10
+
+        # Gini coefficient
+        amounts = [h.get("percentage", 0) for h in holders[:100] if h.get("percentage") is not None]
+        gini = _gini_coefficient(amounts)
+        if gini >= 0.9:
+            score += 40
+        elif gini >= 0.8:
+            score += 30
+        elif gini >= 0.6:
+            score += 15
+
+        # Entropy (low entropy = concentrated)
+        ent = _entropy(amounts)
+        if ent < 0.3:
+            score += 15
+        elif ent < 0.5:
+            score += 8
+
+        return min(score, 100)
+
+    def _score_sniper_clusters(
+        self, clusters: list[HolderCluster], bundled_buys: list[BundledBuy]
+    ) -> float:
+        """Score sniper cluster risk (0-100)."""
+        score = 0.0
+
+        # High-funding-overlap clusters
+        high_overlap = [c for c in clusters if c.funding_overlap_score > 0.6]
+        if high_overlap:
+            total_pct = sum(c.total_supply_pct for c in high_overlap)
+            if total_pct >= 50:
+                score += 50
+            elif total_pct >= 30:
+                score += 35
+            elif total_pct >= 15:
+                score += 20
+
+        # Bundled buys
+        if bundled_buys:
+            score += min(len(bundled_buys) * 5, 30)
+
+        # Time clustering in clusters
+        high_time = [c for c in clusters if c.buy_time_similarity > 0.7]
+        if high_time:
+            score += min(len(high_time) * 10, 25)
+
+        return min(score, 100)
+
+    def _score_launch_timing(
+        self,
+        timing_info: dict[str, Any],
+        buys: list[dict[str, Any]],
+        holders: list[dict[str, Any]],
+    ) -> float:
+        """Score launch timing anomalies (0-100)."""
+        score = 0.0
+
+        # High buy concentration in first 5 minutes
+        ratio = timing_info.get("buy_concentration_ratio", 0)
+        if ratio >= 0.8:
+            score += 50
+        elif ratio >= 0.6:
+            score += 35
+        elif ratio >= 0.4:
+            score += 20
+
+        # Very few unique buyers relative to total buys
+        unique = timing_info.get("unique_buyers_first_block", 0)
+        total = timing_info.get("total_buys_first_blocks", 0)
+        if total > 0 and unique > 0:
+            repeat_rate = total / max(1, unique)
+            if repeat_rate >= 5:
+                score += 30
+            elif repeat_rate >= 3:
+                score += 20
+
+        # Holder count vs buy count mismatch
+        holder_count = len(holders)
+        if holder_count > 0 and total > 0:
+            buys_per_holder = total / holder_count
+            if buys_per_holder >= 3:
+                score += 15
+
+        return min(score, 100)
+
+    def _score_fund_flow(
+        self,
+        bundled_buys: list[BundledBuy],
+        same_funding_count: int,
+        clusters: list[HolderCluster],
+    ) -> float:
+        """Score fund flow risk (0-100)."""
+        score = 0.0
+
+        # Same funding source buys
+        if same_funding_count >= 20:
+            score += 45
+        elif same_funding_count >= 10:
+            score += 30
+        elif same_funding_count >= 5:
+            score += 15
+
+        # Clusters with high funding overlap
+        high_overlap = [c for c in clusters if c.funding_overlap_score > 0.7]
+        if high_overlap:
+            score += min(len(high_overlap) * 15, 30)
+
+        # Overall cluster funding overlap average
+        if clusters:
+            avg_overlap = sum(c.funding_overlap_score for c in clusters) / len(clusters)
+            score += avg_overlap * 20
+
+        return min(score, 100)
+
+    def _compute_bundler_score(self, report: BundlerReport) -> float:
+        """Weighted composite bundler score."""
+        weights = {
+            "supply_concentration": 0.30,
+            "sniper_cluster": 0.25,
+            "launch_timing_anomaly": 0.20,
+            "fund_flow_risk": 0.25,
+        }
+
+        score = (
+            report.supply_concentration_score * weights["supply_concentration"]
+            + report.sniper_cluster_score * weights["sniper_cluster"]
+            + report.launch_timing_anomaly_score * weights["launch_timing_anomaly"]
+            + report.fund_flow_risk_score * weights["fund_flow_risk"]
+        )
+
+        return min(score, 100)

backend/app/canonical_tools.py

@@ -0,0 +1,135 @@
+"""
+Canonical Tool Prices — Single Source of Truth
+127 tools. Enforcement + databus merged.
+This file is THE authoritative list. All endpoints (MCP discovery, x402 catalog, human marketplace) read from this.
+"""
+
+CANONICAL_TOOL_PRICES = {
+    "airdrop_check": {"price_usd": 0.05, "price_atoms": "50000", "category": "market", "trial_free": 2, "description": "airdrop_check"},
+    "airdrop_finder": {"price_usd": 0.05, "price_atoms": "50000", "category": "intelligence", "trial_free": 2, "description": "airdrop_finder"},
+    "alpha_digest": {"price_usd": 0.1, "price_atoms": "100000", "category": "intelligence", "trial_free": 1, "description": "alpha_digest"},
+    "anomaly": {"price_usd": 0.08, "price_atoms": "80000", "category": "security", "trial_free": 0, "description": "anomaly"},
+    "arbitrage_scan": {"price_usd": 0.05, "price_atoms": "50000", "category": "market", "trial_free": 2, "description": "arbitrage_scan"},
+    "arkham_counterparties": {"price_usd": 0.2, "price_atoms": "200000", "category": "elite", "trial_free": 0, "description": "Counterparty intelligence — entity relationship graph and money flow analysis"},
+    "arkham_entity": {"price_usd": 0.1, "price_atoms": "100000", "category": "premium", "trial_free": 1, "description": "Entity resolution — map any address to its real-world owner with confidence scoring"},
+    "arkham_labels": {"price_usd": 0.1, "price_atoms": "100000", "category": "premium", "trial_free": 1, "description": "Institutional entity labels — fund names, exchange wallets, known addresses"},
+    "arkham_portfolio": {"price_usd": 0.25, "price_atoms": "250000", "category": "elite", "trial_free": 0, "description": "Institutional portfolio intelligence — complete holdings, historical performance, attribution"},
+    "arkham_transfers": {"price_usd": 0.2, "price_atoms": "200000", "category": "elite", "trial_free": 0, "description": "Cross-chain transfer tracer — full movement history with entity labeling"},
+    "audit": {"price_usd": 0.05, "price_atoms": "50000", "category": "security", "trial_free": 1, "description": "audit"},
+    "bridge_security": {"price_usd": 0.08, "price_atoms": "80000", "category": "security", "trial_free": 0, "description": "bridge_security"},
+    "bubble_map": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Holder concentration map — visualize whale clusters and distribution"},
+    "bundle_detect": {"price_usd": 0.08, "price_atoms": "80000", "category": "premium", "trial_free": 1, "description": "Bot detector — same-block bundling, MEV patterns, sniper wallet identification"},
+    "bundler_detect": {"price_usd": 0.05, "price_atoms": "50000", "category": "security", "trial_free": 2, "description": "bundler_detect"},
+    "catalog": {"price_usd": 0.0, "price_atoms": "0", "category": "api", "trial_free": 999, "description": "Browse available tools, pricing, and chain support"},
+    "chain_health": {"price_usd": 0.05, "price_atoms": "50000", "category": "market", "trial_free": 0, "description": "chain_health"},
+    "clone_detect": {"price_usd": 0.02, "price_atoms": "20000", "category": "security", "trial_free": 3, "description": "clone_detect"},
+    "cluster": {"price_usd": 0.05, "price_atoms": "50000", "category": "intelligence", "trial_free": 0, "description": "cluster"},
+    "composite_score": {"price_usd": 0.25, "price_atoms": "250000", "category": "premium", "trial_free": 1, "description": "RMI Composite Score — one number combining ALL signals for instant buy/sell/avoid decisions"},
+    "comprehensive_audit": {"price_usd": 0.5, "price_atoms": "500000", "category": "security", "trial_free": 1, "description": "comprehensive_audit"},
+    "contract_scan": {"price_usd": 0.08, "price_atoms": "80000", "category": "premium", "trial_free": 1, "description": "Deep contract audit — static analysis, honeypot detection, vulnerability scan"},
+    "copy_trade_finder": {"price_usd": 0.1, "price_atoms": "100000", "category": "intelligence", "trial_free": 0, "description": "copy_trade_finder"},
+    "cross_chain": {"price_usd": 0.08, "price_atoms": "80000", "category": "premium", "trial_free": 1, "description": "Cross-chain activity — find the same entity across multiple blockchains"},
+    "defi_position": {"price_usd": 0.15, "price_atoms": "150000", "category": "defi", "trial_free": 1, "description": "DeFi position analyzer — LP holdings, impermanent loss estimation, yield sustainability, protocol risk"},
+    "defi_protocols": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "DeFi protocol tracker — TVL, chains, categories, revenue metrics"},
+    "defi_yield_scanner": {"price_usd": 0.08, "price_atoms": "80000", "category": "market", "trial_free": 1, "description": "defi_yield_scanner"},
+    "deployer_history": {"price_usd": 0.05, "price_atoms": "50000", "category": "security", "trial_free": 2, "description": "deployer_history"},
+    "dex_data": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "DEX pool data — liquidity depth, volume, price impact for any token"},
+    "entity_intel": {"price_usd": 0.1, "price_atoms": "100000", "category": "premium", "trial_free": 1, "description": "Entity intelligence — who is this wallet, linked addresses, risk assessment"},
+    "forensic_pack": {"price_usd": 0.35, "price_atoms": "350000", "category": "bundle", "trial_free": 1, "description": "Forensic Investigation Pack — valuation + OSINT + report at 33% discount"},
+    "forensic_valuation": {"price_usd": 0.25, "price_atoms": "250000", "category": "premium", "trial_free": 1, "description": "Institutional-grade token valuation — DCF intrinsic value, comparable analysis with outlier detection, scam probability scoring"},
+    "forensics": {"price_usd": 0.1, "price_atoms": "100000", "category": "analysis", "trial_free": 1, "description": "forensics"},
+    "fresh_pair": {"price_usd": 0.03, "price_atoms": "30000", "category": "security", "trial_free": 3, "description": "fresh_pair"},
+    "funding_source": {"price_usd": 0.08, "price_atoms": "80000", "category": "premium", "trial_free": 1, "description": "Trace where a wallet's funds came from — multi-hop origin analysis"},
+    "gas_forecast": {"price_usd": 0.05, "price_atoms": "50000", "category": "market", "trial_free": 0, "description": "gas_forecast"},
+    "gmgn_smart_money": {"price_usd": 0.05, "price_atoms": "50000", "category": "premium", "trial_free": 1, "description": "Smart money narratives — trending wallets and their trade patterns"},
+    "history": {"price_usd": 0.08, "price_atoms": "80000", "category": "analysis", "trial_free": 2, "description": "Historical scanner time-series — risk/liquidity/volume/price trends over hours"},
+    "honeypot_check": {"price_usd": 0.05, "price_atoms": "50000", "category": "security", "trial_free": 2, "description": "honeypot_check"},
+    "human-execute": {"price_usd": 0.02, "price_atoms": "20000", "category": "api", "trial_free": 2, "description": "Human-in-the-loop execution — wallet-based payment for manual crypto investigation tasks"},
+    "insider": {"price_usd": 0.1, "price_atoms": "100000", "category": "intelligence", "trial_free": 0, "description": "insider"},
+    "insider_network": {"price_usd": 0.1, "price_atoms": "100000", "category": "intelligence", "trial_free": 0, "description": "insider_network"},
+    "investigation_report": {"price_usd": 0.2, "price_atoms": "200000", "category": "premium", "trial_free": 1, "description": "Full investigation report — on-chain forensics, financial valuation, OSINT findings, scam scoring in one deliverable"},
+    "kol_performance": {"price_usd": 0.1, "price_atoms": "100000", "category": "intelligence", "trial_free": 0, "description": "kol_performance"},
+    "launch": {"price_usd": 0.03, "price_atoms": "30000", "category": "launchpad", "trial_free": 2, "description": "launch"},
+    "launch_intel": {"price_usd": 0.05, "price_atoms": "50000", "category": "launchpad", "trial_free": 2, "description": "launch_intel"},
+    "liquidity_depth": {"price_usd": 0.05, "price_atoms": "50000", "category": "market", "trial_free": 2, "description": "liquidity_depth"},
+    "liquidity_flow": {"price_usd": 0.08, "price_atoms": "80000", "category": "intelligence", "trial_free": 0, "description": "liquidity_flow"},
+    "liquidity_migration": {"price_usd": 0.05, "price_atoms": "50000", "category": "security", "trial_free": 2, "description": "liquidity_migration"},
+    "listing_predictor": {"price_usd": 0.08, "price_atoms": "80000", "category": "intelligence", "trial_free": 1, "description": "listing_predictor"},
+    "market_movers": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "Top gainers, losers, and volume movers across all chains"},
+    "market_overview": {"price_usd": 0.05, "price_atoms": "50000", "category": "market", "trial_free": 0, "description": "market_overview"},
+    "mcp-proxy": {"price_usd": 0.01, "price_atoms": "10000", "category": "api", "trial_free": 5, "description": "MCP protocol proxy — route tool calls through the x402 payment layer"},
+    "meme_vibe_score": {"price_usd": 0.01, "price_atoms": "10000", "category": "social", "trial_free": 3, "description": "Meme token vibe scoring — sentiment, community strength, and virality analysis"},
+    "mev_alert": {"price_usd": 0.08, "price_atoms": "80000", "category": "security", "trial_free": 1, "description": "mev_alert"},
+    "mev_detect": {"price_usd": 0.15, "price_atoms": "150000", "category": "security", "trial_free": 2, "description": "MEV/Sandwich attack detection — sandwich attacks, frontrunning, arbitrage extraction, MEV bot identification"},
+    "mev_protection": {"price_usd": 0.08, "price_atoms": "80000", "category": "security", "trial_free": 0, "description": "mev_protection"},
+    "nansen_labels": {"price_usd": 0.15, "price_atoms": "150000", "category": "elite", "trial_free": 0, "description": "Smart money labels — fund tags, whale classifications, and institutional wallet mapping"},
+    "nansen_smart_money": {"price_usd": 0.15, "price_atoms": "150000", "category": "elite", "trial_free": 0, "description": "Smart money tracker — top trader activity, position tracking, alpha signals"},
+    "narrative": {"price_usd": 0.05, "price_atoms": "50000", "category": "social", "trial_free": 3, "description": "Market narrative engine — what is the market saying about this token RIGHT NOW"},
+    "news": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "Crypto news feed — aggregated headlines, filtered by topic"},
+    "nft_wash_detector": {"price_usd": 0.1, "price_atoms": "100000", "category": "analysis", "trial_free": 1, "description": "nft_wash_detector"},
+    "osint_identity_hunt": {"price_usd": 0.15, "price_atoms": "150000", "category": "premium", "trial_free": 2, "description": "Cross-platform OSINT investigation — hunt usernames across 400+ networks, domain intelligence, stealth page capture"},
+    "portfolio": {"price_usd": 0.15, "price_atoms": "150000", "category": "elite", "trial_free": 0, "description": "Multi-wallet portfolio — consolidated holdings, PnL, and risk across all wallets"},
+    "portfolio_aggregate": {"price_usd": 0.1, "price_atoms": "100000", "category": "analysis", "trial_free": 1, "description": "portfolio_aggregate"},
+    "portfolio_risk": {"price_usd": 0.2, "price_atoms": "200000", "category": "premium", "trial_free": 1, "description": "Cross-chain portfolio risk dashboard — unified risk across multiple wallets and chains"},
+    "portfolio_tracker": {"price_usd": 0.1, "price_atoms": "100000", "category": "analysis", "trial_free": 0, "description": "portfolio_tracker"},
+    "prediction_markets": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Prediction market odds — event probabilities and trading volumes"},
+    "prediction_signals": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Trading signals — sentiment, momentum, and contrarian indicators"},
+    "profile_flip": {"price_usd": 0.03, "price_atoms": "30000", "category": "security", "trial_free": 3, "description": "profile_flip"},
+    "protocol_risk": {"price_usd": 0.08, "price_atoms": "80000", "category": "security", "trial_free": 1, "description": "protocol_risk"},
+    "pulse": {"price_usd": 0.01, "price_atoms": "10000", "category": "market", "trial_free": 3, "description": "pulse"},
+    "rag_search": {"price_usd": 0.05, "price_atoms": "50000", "category": "premium", "trial_free": 2, "description": "Knowledge search — query 17K+ crypto documents for research, analysis, and deep answers"},
+    "reputation_score": {"price_usd": 0.1, "price_atoms": "100000", "category": "premium", "trial_free": 1, "description": "Comprehensive 0-100 trust score combining wallet labels, scam databases, deployer history, and RAG similarity matching"},
+    "risk_monitor": {"price_usd": 0.05, "price_atoms": "50000", "category": "security", "trial_free": 1, "description": "risk_monitor"},
+    "risk_scan": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Quick rug risk scan — honeypot, liquidity lock, ownership, and contract flags"},
+    "rug_probability": {"price_usd": 0.15, "price_atoms": "150000", "category": "premium", "trial_free": 1, "description": "Predictive rug pull probability 0-100 — honeypot + liquidity + deployer + social signals"},
+    "rug_pull_predictor": {"price_usd": 0.1, "price_atoms": "100000", "category": "security", "trial_free": 0, "description": "rug_pull_predictor"},
+    "rugmaps_analysis": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Holder distribution analysis — risk scoring, dump patterns, concentration"},
+    "rugshield": {"price_usd": 0.02, "price_atoms": "20000", "category": "security", "trial_free": 3, "description": "rugshield"},
+    "scam_database": {"price_usd": 0.03, "price_atoms": "30000", "category": "security", "trial_free": 3, "description": "scam_database"},
+    "sentiment": {"price_usd": 0.03, "price_atoms": "30000", "category": "social", "trial_free": 0, "description": "sentiment"},
+    "sentiment_spike": {"price_usd": 0.05, "price_atoms": "50000", "category": "social", "trial_free": 2, "description": "sentiment_spike"},
+    "sentinel_deep": {"price_usd": 0.1, "price_atoms": "100000", "category": "premium", "trial_free": 1, "description": "Full threat scan — deep contract analysis, risk scoring, threat intelligence"},
+    "smart_money": {"price_usd": 0.2, "price_atoms": "200000", "category": "intelligence", "trial_free": 1, "description": "Smart Money P&L Tracker — real profitability-based wallet tracking, find the actual profitable traders"},
+    "smart_money_alpha": {"price_usd": 0.01, "price_atoms": "10000", "category": "intelligence", "trial_free": 3, "description": "Smart money alpha signals — track wallets that consistently outperform the market"},
+    "smartmoney": {"price_usd": 0.05, "price_atoms": "50000", "category": "intelligence", "trial_free": 1, "description": "smartmoney"},
+    "sniper_alert": {"price_usd": 0.05, "price_atoms": "50000", "category": "launchpad", "trial_free": 2, "description": "sniper_alert"},
+    "sniper_detect": {"price_usd": 0.08, "price_atoms": "80000", "category": "intelligence", "trial_free": 1, "description": "sniper_detect"},
+    "social_feed": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "Social sentiment feed — what crypto Twitter and Telegram are saying"},
+    "social_signal": {"price_usd": 0.1, "price_atoms": "100000", "category": "social", "trial_free": 0, "description": "social_signal"},
+    "socialfi_resolve": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 3, "description": "Resolve social identity — ENS names, Farcaster profiles, linked addresses"},
+    "syndicate_scan": {"price_usd": 0.08, "price_atoms": "80000", "category": "intelligence", "trial_free": 1, "description": "syndicate_scan"},
+    "syndicate_track": {"price_usd": 0.1, "price_atoms": "100000", "category": "intelligence", "trial_free": 1, "description": "syndicate_track"},
+    "threat_check": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Threat intelligence check — known scams, malicious patterns, risk scoring"},
+    "token_age": {"price_usd": 0.01, "price_atoms": "10000", "category": "security", "trial_free": 5, "description": "token_age"},
+    "token_comparison": {"price_usd": 0.08, "price_atoms": "80000", "category": "analysis", "trial_free": 0, "description": "token_comparison"},
+    "token_deep_dive": {"price_usd": 0.1, "price_atoms": "100000", "category": "analysis", "trial_free": 0, "description": "token_deep_dive"},
+    "token_detail": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Full token intelligence — market cap, volume, liquidity, holders, risk flags"},
+    "token_price": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "Get real-time token price with consensus from multiple sources"},
+    "token_watch_alerts": {"price_usd": 0.0, "price_atoms": "0", "category": "monitoring", "trial_free": 999, "description": "token_watch_alerts"},
+    "token_watch_check": {"price_usd": 0.03, "price_atoms": "30000", "category": "monitoring", "trial_free": 5, "description": "One-shot token status check — current LP, price, volume, and rug risk warnings"},
+    "token_watch_create": {"price_usd": 0.05, "price_atoms": "50000", "category": "monitoring", "trial_free": 3, "description": "Set token monitoring watch — alerts when LP drops, price changes, or rug indicators detected"},
+    "token_watch_list": {"price_usd": 0.0, "price_atoms": "0", "category": "monitoring", "trial_free": 999, "description": "token_watch_list"},
+    "trending": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "Trending tokens across chains — hottest movers right now"},
+    "tvl": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 5, "description": "DeFi TVL data — protocol-level totals, chain breakdowns, yields"},
+    "tw_profile": {"price_usd": 0.01, "price_atoms": "10000", "category": "social", "trial_free": 0, "description": "tw_profile"},
+    "tw_search": {"price_usd": 0.01, "price_atoms": "10000", "category": "social", "trial_free": 0, "description": "tw_search"},
+    "tw_timeline": {"price_usd": 0.01, "price_atoms": "10000", "category": "social", "trial_free": 0, "description": "tw_timeline"},
+    "unlock_calendar": {"price_usd": 0.03, "price_atoms": "30000", "category": "market", "trial_free": 3, "description": "unlock_calendar"},
+    "urlcheck": {"price_usd": 0.01, "price_atoms": "10000", "category": "security", "trial_free": 3, "description": "urlcheck"},
+    "wallet": {"price_usd": 0.05, "price_atoms": "50000", "category": "analysis", "trial_free": 1, "description": "wallet"},
+    "wallet_balance": {"price_usd": 0.01, "price_atoms": "10000", "category": "basic", "trial_free": 3, "description": "Check any wallet's balance across chains — multi-chain support"},
+    "wallet_cluster": {"price_usd": 0.08, "price_atoms": "80000", "category": "premium", "trial_free": 1, "description": "Syndicate mapper — find related wallets via funding patterns and heuristics"},
+    "wallet_graph": {"price_usd": 0.1, "price_atoms": "100000", "category": "intelligence", "trial_free": 0, "description": "wallet_graph"},
+    "wallet_labels": {"price_usd": 0.02, "price_atoms": "20000", "category": "basic", "trial_free": 3, "description": "Identify who owns a wallet — entity labels, tags, and known affiliations"},
+    "wallet_pnl": {"price_usd": 0.1, "price_atoms": "100000", "category": "analysis", "trial_free": 0, "description": "wallet_pnl"},
+    "wallet_profile": {"price_usd": 0.05, "price_atoms": "50000", "category": "premium", "trial_free": 1, "description": "Complete wallet profile — labels, PnL summary, risk score, related wallets"},
+    "wallet_tokens": {"price_usd": 0.05, "price_atoms": "50000", "category": "premium", "trial_free": 1, "description": "All tokens held by a wallet — balances, USD values, allocation breakdown"},
+    "wash_trade_detect": {"price_usd": 0.15, "price_atoms": "150000", "category": "security", "trial_free": 2, "description": "Wash Trading & Insider Detection — artificial volume, coordinated buying, insider accumulation patterns"},
+    "wash_trading": {"price_usd": 0.08, "price_atoms": "80000", "category": "security", "trial_free": 1, "description": "wash_trading"},
+    "webhook_list": {"price_usd": 0.0, "price_atoms": "0", "category": "monitoring", "trial_free": 999, "description": "List registered webhooks for an address"},
+    "webhook_register": {"price_usd": 0.02, "price_atoms": "20000", "category": "monitoring", "trial_free": 2, "description": "Register webhook URL for real-time monitoring alerts — rug pulls, whale moves, price crashes"},
+    "whale": {"price_usd": 0.15, "price_atoms": "150000", "category": "intelligence", "trial_free": 1, "description": "whale"},
+    "whale_accumulation": {"price_usd": 0.08, "price_atoms": "80000", "category": "intelligence", "trial_free": 1, "description": "whale_accumulation"},
+    "whale_profile": {"price_usd": 0.05, "price_atoms": "50000", "category": "intelligence", "trial_free": 2, "description": "whale_profile"},
+    "whale_scan": {"price_usd": 0.03, "price_atoms": "30000", "category": "intelligence", "trial_free": 3, "description": "whale_scan"},
+}