/token-holder-analysis

name: token-holder-analysis
description: Token holder distribution, concentration metrics, insider detection, and supply analysis for Solana tokens

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

| Source | What It Provides | Auth | |--------|-----------------|------| | **Solana RPC** (`getTokenLargestAccounts`) | Top 20 holders, supply | RPC key | | **Helius DAS** (`getAsset`, token accounts) | Parsed holder data, metadata | API key | | **SolanaTracker** (`/tokens/{t}/holders/top`) | Top 100 holders, bundler detection | API key | | **Birdeye** (`/defi/token_security`) | Top 10 %, creator balance, freeze/mint auth | API key |

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)