Token Holder Analysis

Token Holder Analysis — Concentration, Distribution & Risk

Analyze who holds a token, how concentrated ownership is, and whether insider patterns suggest risk. This is a critical pre-trade safety check — high concentration means a few wallets can crash the price.

Quick Start

import httpx
import math

# Using Helius DAS API for holder data
HELIUS_KEY = os.getenv("HELIUS_API_KEY", "")
HELIUS = f"https://mainnet.helius-rpc.com/?api-key={HELIUS_KEY}"

# Or using SolanaTracker for holder + risk data
ST_KEY = os.getenv("SOLANATRACKER_API_KEY", "")
ST = "https://data.solanatracker.io"

# Get top holders via RPC
def get_top_holders(mint: str) -> list[dict]:
    resp = httpx.post(HELIUS, json={
        "jsonrpc": "2.0", "id": 1,
        "method": "getTokenLargestAccounts",
        "params": [mint],
    })
    return resp.json()["result"]["value"]

holders = get_top_holders("TOKEN_MINT")

Data Sources

Concentration Metrics

Top-N Holder Percentage

The simplest measure — what % of supply do the top N holders control?

def top_n_percentage(holders: list[dict], supply: int, n: int = 10) -> float:
    """Calculate percentage held by top N holders.

    Args:
        holders: Sorted list of holders (largest first).
        supply: Total token supply.
        n: Number of top holders.

    Returns:
        Percentage (0-100) held by top N.
    """
    top_n_amount = sum(int(h.get("amount", 0)) for h in holders[:n])
    return top_n_amount / supply * 100 if supply > 0 else 0

Risk thresholds:

• Top 10 < 30%: Well distributed
• Top 10 30-50%: Moderate concentration
• Top 10 50-80%: High concentration — significant dump risk
• Top 10 > 80%: Extreme — likely controlled by a few wallets

Gini Coefficient

Measures inequality of token distribution (0 = perfectly equal, 1 = one holder owns everything).

def gini_coefficient(amounts: list[float]) -> float:
    """Calculate Gini coefficient for holder distribution.

    Args:
        amounts: List of holder amounts (any order).

    Returns:
        Gini coefficient between 0 and 1.
    """
    if not amounts or all(a == 0 for a in amounts):
        return 0.0
    sorted_amounts = sorted(amounts)
    n = len(sorted_amounts)
    cumsum = sum((i + 1) * a for i, a in enumerate(sorted_amounts))
    total = sum(sorted_amounts)
    return (2 * cumsum) / (n * total) - (n + 1) / n

Interpretation for crypto tokens:

• Gini < 0.6: Unusual, very well distributed
• Gini 0.6-0.8: Typical for established tokens
• Gini 0.8-0.95: Common for newer tokens
• Gini > 0.95: Extreme concentration, high risk

Herfindahl-Hirschman Index (HHI)

Measures market concentration — sum of squared market shares.

def hhi(amounts: list[float]) -> float:
    """Calculate HHI for holder concentration.

    Args:
        amounts: List of holder amounts.

    Returns:
        HHI value (0-10000). Higher = more concentrated.
    """
    total = sum(amounts)
    if total == 0:
        return 0.0
    shares = [a / total * 100 for a in amounts]
    return sum(s ** 2 for s in shares)

Interpretation:

• HHI < 1500: Competitive (unconcentrated)
• HHI 1500-2500: Moderately concentrated
• HHI > 2500: Highly concentrated

Nakamoto Coefficient

Minimum number of holders needed to control >50% of supply.

def nakamoto_coefficient(amounts: list[float]) -> int:
    """Calculate Nakamoto coefficient (holders needed for 51%).

    Args:
        amounts: Sorted list of holder amounts (largest first).

    Returns:
        Number of holders needed for majority control.
    """
    total = sum(amounts)
    if total == 0:
        return 0
    threshold = total * 0.51
    cumulative = 0
    for i, amount in enumerate(sorted(amounts, reverse=True)):
        cumulative += amount
        if cumulative >= threshold:
            return i + 1
    return len(amounts)

Insider Detection Patterns

Bundler Detection

Bundlers use atomic transaction bundles (via Jito) to execute coordinated buys at token launch. Detection signals:

def detect_bundler_patterns(holders: list[dict], first_buyers: list[dict]) -> dict:
    """Identify potential bundler activity.

    Args:
        holders: Current top holders.
        first_buyers: Early buyers from SolanaTracker /first-buyers endpoint.

    Returns:
        Bundler risk analysis.
    """
    early_still_holding = [
        b for b in first_buyers
        if b.get("holdingAmount", 0) > 0
    ]
    early_holder_pct = sum(
        b.get("holdingPercentage", 0) for b in early_still_holding
    )

    return {
        "early_buyers_count": len(first_buyers),
        "still_holding_count": len(early_still_holding),
        "early_holder_pct": round(early_holder_pct, 2),
        "risk": "HIGH" if early_holder_pct > 20 else
                "MODERATE" if early_holder_pct > 10 else "LOW",
    }

Developer Holdings

Creator wallet retention is a risk signal:

def check_developer_risk(token_data: dict) -> dict:
    """Check developer wallet holdings and authority.

    Args:
        token_data: Token info from SolanaTracker or Birdeye.

    Returns:
        Developer risk assessment.
    """
    risk = token_data.get("risk", {})
    flags = []

    # Check creator balance (from Birdeye security endpoint)
    creator_balance = token_data.get("creatorBalance", 0)
    if creator_balance > 10:
        flags.append(f"Creator holds {creator_balance:.1f}% of supply")

    # Check mint authority
    if token_data.get("mintAuthority") or token_data.get("ownerAddress"):
        flags.append("Mint authority NOT renounced — supply can increase")

    # Check freeze authority
    if token_data.get("freezeAuthority") or token_data.get("freezeable"):
        flags.append("Freeze authority enabled — tokens can be frozen")

    return {
        "flags": flags,
        "risk_level": "HIGH" if len(flags) >= 2 else
                      "MODERATE" if len(flags) == 1 else "LOW",
    }

Sniper Detection

Snipers buy in the first few seconds/blocks after token creation:

def analyze_sniper_concentration(first_buyers: list[dict], total_supply: float) -> dict:
    """Analyze sniper impact on holder distribution.

    Args:
        first_buyers: First buyers data from SolanaTracker.
        total_supply: Total token supply.

    Returns:
        Sniper concentration analysis.
    """
    # Snipers typically buy in first 10 seconds
    snipers = first_buyers[:10]  # first N buyers are potential snipers
    sniper_holding = sum(b.get("holdingAmount", 0) for b in snipers)
    sniper_pct = sniper_holding / total_supply * 100 if total_supply > 0 else 0

    return {
        "sniper_count": len(snipers),
        "sniper_holding_pct": round(sniper_pct, 2),
        "sniper_still_holding": sum(1 for s in snipers if s.get("holdingAmount", 0) > 0),
        "risk": "HIGH" if sniper_pct > 15 else
                "MODERATE" if sniper_pct > 5 else "LOW",
    }

Complete Analysis Pipeline

def full_holder_analysis(mint: str) -> dict:
    """Run complete holder analysis for a token.

    Combines RPC, SolanaTracker, and computed metrics.
    """
    # 1. Get supply and top holders via RPC
    supply_result = rpc_call("getTokenSupply", [mint])
    total_supply = int(supply_result["result"]["value"]["amount"])

    holders = get_top_holders(mint)
    amounts = [int(h["amount"]) for h in holders]

    # 2. Compute concentration metrics
    metrics = {
        "total_supply": total_supply,
        "holder_count": len(holders),
        "top_1_pct": top_n_percentage(holders, total_supply, 1),
        "top_5_pct": top_n_percentage(holders, total_supply, 5),
        "top_10_pct": top_n_percentage(holders, total_supply, 10),
        "top_20_pct": top_n_percentage(holders, total_supply, 20),
        "gini": round(gini_coefficient(amounts), 4),
        "hhi": round(hhi(amounts), 1),
        "nakamoto": nakamoto_coefficient(amounts),
    }

    # 3. Risk classification
    t10 = metrics["top_10_pct"]
    if t10 > 80:
        metrics["risk"] = "EXTREME"
    elif t10 > 50:
        metrics["risk"] = "HIGH"
    elif t10 > 30:
        metrics["risk"] = "MODERATE"
    else:
        metrics["risk"] = "LOW"

    return metrics

Risk Classification Summary

Known Exclusions

When computing holder concentration, exclude these addresses which are programs/pools, not individual holders:

• DEX pool addresses (Raydium, Orca, Meteora pools)
• Token program vaults
• Bridge escrow accounts
• Known burn addresses

KNOWN_PROGRAMS = {
    "5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1",  # Raydium authority
    "GThUX1Atko4tqhN2NaiTazWSeFWMuiUvfFnyJyUghFMJ",  # Orca authority
    # Add more as needed
}

def filter_real_holders(holders: list[dict]) -> list[dict]:
    """Remove known program/pool accounts from holder list."""
    return [h for h in holders if h.get("address") not in KNOWN_PROGRAMS]

Files

References

• references/concentration_metrics.md — Mathematical formulas and derivations for Gini, HHI, Nakamoto
• references/insider_patterns.md — Bundler, sniper, and developer detection methodology
• references/data_sources.md — How to fetch holder data from each API source

Scripts

• scripts/analyze_holders.py — Full holder analysis: fetch holders, compute metrics, generate risk report
• scripts/concentration_scanner.py — Scan multiple tokens for concentration risk

Concentration Metrics — Formulas & Interpretation

Top-N Holder Percentage

The simplest concentration measure. Sums the holdings of the N largest holders as a percentage of total supply.

Formula:

Top_N% = (Σ holdings[i] for i=1..N) / total_supply × 100

Thresholds for Solana tokens:

Important: Always exclude known program accounts (DEX pools, bridge escrows, burn addresses) from holder counts. Including pool liquidity as a "holder" skews the metric.

---

Gini Coefficient

Measures inequality of distribution. Originally from economics (income inequality), applied here to token holdings.

Formula:

G = (2 × Σ(i × x_i)) / (n × Σ(x_i)) - (n + 1) / n

where x_i are amounts sorted ascending, i is 1-indexed position, n is holder count

Equivalent formula (via mean absolute difference):

G = Σ_i Σ_j |x_i - x_j| / (2 × n² × μ)

where μ is the mean holding

Range: 0 to 1

• 0 = perfectly equal (every holder has the same amount)
• 1 = maximally unequal (one holder owns everything)

Crypto-specific thresholds:

Limitations:

• Gini is sensitive to the number of holders included. Computing over top 20 holders (RPC limit) vs. all holders gives different values.
• For meaningful comparison, always compute over the same sample size.
• Gini doesn't distinguish between distributions with the same inequality but different shapes (e.g., one whale vs. several large holders).

---

Herfindahl-Hirschman Index (HHI)

Sum of squared market shares. Originally used for antitrust analysis (market concentration). More sensitive to large holders than Gini.

Formula:

HHI = Σ(s_i²)

where s_i = (holding_i / total_supply) × 100  (percentage share)

Range: 0 to 10,000

• Minimum (n equal holders): HHI = 10000/n
• Maximum (one holder): HHI = 10,000

Thresholds (adapted from DOJ antitrust guidelines):

Advantage over Gini: HHI is more sensitive to the presence of dominant holders. A distribution with one 50% holder and many small holders will have a much higher HHI than a distribution with several 10% holders, even if both have similar Gini values.

---

Nakamoto Coefficient

Minimum number of entities needed to control >50% of the system. Named after Satoshi Nakamoto.

Formula:

N = min k such that Σ(holding_i for top k holders) > 0.51 × total_supply

Interpretation:

Notes:

• Lower bound for Nakamoto is 1. If the largest holder owns >50%, Nakamoto = 1.
• The 51% threshold can be adjusted (e.g., 33% for tokens where 1/3 can block governance).
• Nakamoto coefficient is particularly useful for governance tokens where voting power matters.

---

Shannon Entropy

Information-theoretic measure of distribution randomness. Not commonly used but provides additional perspective.

Formula:

H = -Σ(p_i × log2(p_i))

where p_i = holding_i / total_supply

Range: 0 to log2(n)

• 0 = one holder owns everything
• log2(n) = perfectly equal distribution

Higher entropy = more decentralized.

---

Combining Metrics

No single metric tells the full story. Use them together:

def comprehensive_risk(top_10_pct, gini, hhi, nakamoto):
    """Combine metrics into a single risk score."""
    scores = {
        "top10": 3 if top_10_pct > 80 else 2 if top_10_pct > 50 else 1 if top_10_pct > 30 else 0,
        "gini": 3 if gini > 0.95 else 2 if gini > 0.85 else 1 if gini > 0.7 else 0,
        "hhi": 3 if hhi > 5000 else 2 if hhi > 2500 else 1 if hhi > 1500 else 0,
        "nakamoto": 3 if nakamoto <= 1 else 2 if nakamoto <= 3 else 1 if nakamoto <= 5 else 0,
    }
    total = sum(scores.values())
    if total >= 9: return "EXTREME"
    if total >= 6: return "HIGH"
    if total >= 3: return "MODERATE"
    return "LOW"

Holder Analysis — Data Sources

Source Comparison

Method 1: Solana RPC (Free, Basic)

Best for: Quick top-20 check, total supply, mint/freeze authority status.

# Top 20 holders
result = rpc_call("getTokenLargestAccounts", [mint])
holders = result["value"]  # [{address, amount, decimals, uiAmount}]

# Total supply
result = rpc_call("getTokenSupply", [mint])
supply = result["value"]  # {amount, decimals, uiAmount}

# Mint/freeze authority (from mint account data)
result = rpc_call("getAccountInfo", [mint, {"encoding": "jsonParsed"}])
mint_info = result["value"]["data"]["parsed"]["info"]
# mint_info["mintAuthority"] — None if renounced
# mint_info["freezeAuthority"] — None if disabled

Limitations: Only top 20 holders. No holder count. No insider detection.

Method 2: Helius DAS API

Best for: Token metadata, parsed account data, fungible token details.

# Token metadata via DAS
resp = httpx.post(f"https://mainnet.helius-rpc.com/?api-key={KEY}", json={
    "jsonrpc": "2.0", "id": 1,
    "method": "getAsset",
    "params": {"id": mint},
})
asset = resp.json()["result"]
# asset["authorities"] — mint/freeze authority info
# asset["token_info"]["supply"] — total supply
# asset["content"]["metadata"] — name, symbol, image

Limitations: Doesn't directly provide holder lists. Use with RPC for complete picture.

Method 3: SolanaTracker API (Most Complete)

Best for: Full holder analysis including bundlers, snipers, risk scoring.

HEADERS = {"x-api-key": ST_KEY}

# Top 100 holders
resp = httpx.get(f"https://data.solanatracker.io/tokens/{mint}/holders/top", headers=HEADERS)
holders = resp.json()

# Top 20 (lighter call)
resp = httpx.get(f"https://data.solanatracker.io/tokens/{mint}/holders/top20", headers=HEADERS)

# Bundler detection
resp = httpx.get(f"https://data.solanatracker.io/tokens/{mint}/bundlers", headers=HEADERS)
bundlers = resp.json()

# First buyers with PnL
resp = httpx.get(f"https://data.solanatracker.io/first-buyers/{mint}", headers=HEADERS)
first_buyers = resp.json()

# Full token info with risk score
resp = httpx.get(f"https://data.solanatracker.io/tokens/{mint}", headers=HEADERS)
token = resp.json()
risk_score = token["risk"]["score"]  # 1-10

Method 4: Birdeye API

Best for: Quick security check (mint/freeze authority, top 10 concentration).

# Token security info
resp = httpx.get("https://public-api.birdeye.so/defi/token_security",
    headers={"X-API-KEY": BE_KEY, "x-chain": "solana"},
    params={"address": mint})
security = resp.json()["data"]
# security["top10HolderPercent"]
# security["ownerAddress"] — mint authority (None if renounced)
# security["freezeable"]
# security["mutableMetadata"]
# security["creatorBalance"]

Recommended Pipeline

For a thorough pre-trade holder analysis:

def full_holder_check(mint: str) -> dict:
    """Complete holder analysis using best available data sources."""

    # 1. Quick check via RPC (free, always available)
    supply = get_token_supply(mint)
    top_20 = get_largest_accounts(mint)

    # 2. Risk score from SolanaTracker (if key available)
    if ST_KEY:
        token_data = st_get(f"/tokens/{mint}")
        risk_score = token_data.get("risk", {}).get("score", 0)
        bundlers = st_get(f"/tokens/{mint}/bundlers")

    # 3. Security check from Birdeye (if key available)
    if BE_KEY:
        security = birdeye_get("/defi/token_security", {"address": mint})

    # 4. Compute concentration metrics from RPC data
    amounts = [int(h["amount"]) for h in top_20]
    metrics = compute_concentration(amounts, int(supply["amount"]))

    return {
        "supply": supply,
        "top_holders": top_20,
        "concentration": metrics,
        "risk_score": risk_score,
        "bundlers": bundlers,
        "security": security,
    }

Caching Considerations

Holder data changes slowly compared to price data. Reasonable cache TTLs:

Insider Detection Patterns

Overview

"Insider" in Solana token trading refers to wallets that have an unfair advantage — they bought before public availability, used transaction bundles for guaranteed early execution, or are connected to the token creator. Detecting these patterns is a critical pre-trade safety check.

Pattern 1: Bundler Detection

What is bundling?

Bundlers use Jito or similar services to submit multiple transactions atomically in a single block. This guarantees execution order, allowing coordinated buys at token launch.

Detection signals

1. Multiple buys in the same block/slot as token creation 2. Multiple wallets buying the exact same amount in the first slots 3. Wallets that share funding sources (funded from the same parent wallet) 4. High holding percentage from first-block buyers

Data sources

• SolanaTracker /tokens/{token}/bundlers — pre-computed bundler detection
• SolanaTracker /first-buyers/{token} — first buyers with PnL
• Helius Enhanced Transactions — parse early transactions for patterns

Risk interpretation

Pattern 2: Sniper Detection

What is sniping?

Snipers use automated bots to buy tokens within the first few seconds of liquidity being added. They achieve near-zero entry prices on bonding curves or DEX launches.

Detection signals

1. Buy transactions within first 1-10 seconds of pool creation 2. Wallet has many "first buy" patterns across different tokens 3. Bot-like transaction patterns (fixed amounts, consistent timing) 4. Currently holding large % of supply from initial snipe

Analysis approach

def is_sniper_wallet(wallet_trades: list[dict], token_created_at: int) -> bool:
    """Check if wallet sniped the token launch."""
    first_buy = next(
        (t for t in wallet_trades if t["type"] == "buy"),
        None
    )
    if first_buy is None:
        return False
    # Bought within 10 seconds of creation
    return first_buy["timestamp"] - token_created_at < 10

Pattern 3: Developer / Creator Analysis

Risk factors

1. Creator still holds tokens — can dump at any time 2. Mint authority not renounced — creator can mint more tokens 3. Freeze authority active — creator can freeze token accounts 4. Creator wallet funded by known rug accounts 5. Creator deployed multiple tokens that failed (serial deployer)

Data sources

• Birdeye /defi/token_security — mint authority, freeze authority, creator balance
• SolanaTracker /tokens/{token} — risk score includes these checks
• SolanaTracker /tokens/deployer/{addr} — all tokens by the same deployer
• Direct RPC — check mint account for authority fields

Serial deployer detection

def check_deployer_history(deployer: str, api_key: str) -> dict:
    """Check deployer's track record."""
    resp = httpx.get(
        f"https://data.solanatracker.io/tokens/deployer/{deployer}",
        headers={"x-api-key": api_key},
    )
    tokens = resp.json()

    rugged = sum(1 for t in tokens if t.get("risk", {}).get("rugged"))
    low_risk = sum(1 for t in tokens if t.get("risk", {}).get("score", 0) >= 7)

    return {
        "total_deployments": len(tokens),
        "rugged_count": rugged,
        "low_risk_count": low_risk,
        "serial_rug": rugged > 3,
    }

Pattern 4: Connected Wallet Clusters

What to look for

• Wallets funded from the same source around token launch
• Wallets that only ever trade the same tokens
• Wallets that buy and sell in coordinated timing patterns

Analysis approach

This requires transaction history analysis: 1. For each top holder, trace their funding source (SOL origin) 2. Cluster wallets that share the same funding source 3. Flag clusters that collectively hold >10% of supply

def trace_funding_source(wallet: str, depth: int = 2) -> list[str]:
    """Trace SOL funding sources for a wallet.

    Use Helius Enhanced Transactions to find incoming SOL transfers.
    Returns list of funding source addresses.
    """
    sources = []
    resp = httpx.get(
        f"https://api.helius.xyz/v0/addresses/{wallet}/transactions",
        params={"api-key": HELIUS_KEY, "type": "TRANSFER"},
    )
    for tx in resp.json()[:20]:
        for transfer in tx.get("nativeTransfers", []):
            if transfer.get("toUserAccount") == wallet:
                sources.append(transfer["fromUserAccount"])
    return sources

Pattern 5: Wash Trading Detection

Signals

• Same wallet appearing as both buyer and seller (self-trades)
• High volume but low unique wallet count
• Volume spikes with no corresponding price movement
• Buy/sell ratio extremely close to 1.0 across many time periods

Quick check

def wash_trading_check(pair_data: dict) -> dict:
    """Quick wash trading heuristic from DexScreener data."""
    txns = pair_data.get("txns", {}).get("h24", {})
    buys = txns.get("buys", 0)
    sells = txns.get("sells", 0)
    total = buys + sells

    volume = pair_data.get("volume", {}).get("h24", 0)
    liquidity = pair_data.get("liquidity", {}).get("usd", 0)

    flags = []
    if total > 0 and abs(buys - sells) / total < 0.05:
        flags.append("Buy/sell count suspiciously balanced")
    if liquidity > 0 and volume / liquidity > 50:
        flags.append(f"Volume/liquidity ratio extremely high ({volume/liquidity:.0f}x)")

    return {"flags": flags, "suspicious": len(flags) > 0}

Combining Insider Signals

Weight multiple signals for a composite insider risk score:

Score 0-3: Low insider risk Score 4-7: Moderate — proceed with caution Score 8-12: High — small positions only Score 13+: Extreme — avoid