MCPInstall

token-holder-analysis

Token holder distribution, concentration metrics, insider detection, and supply analysis for Solana tokens

Installs
436
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/agiprolabs/claude-trading-skills --skill token-holder-analysis
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads token-holder-analysis automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

SourceWhat It ProvidesAuth
Solana RPC (getTokenLargestAccounts)Top 20 holders, supplyRPC key
Helius DAS (getAsset, token accounts)Parsed holder data, metadataAPI key
SolanaTracker (/tokens/{t}/holders/top)Top 100 holders, bundler detectionAPI key
Birdeye (/defi/token_security)Top 10 %, creator balance, freeze/mint authAPI 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)
    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

MetricLow RiskModerateHighExtreme
Top 10 %<30%30-50%50-80%>80%
Gini<0.70.7-0.850.85-0.95>0.95
HHI<15001500-25002500-5000>5000
Nakamoto>105-102-41
Mint AuthRenounced—ActiveActive + high dev %
Freeze AuthDisabled—EnabledEnabled + low liq

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

FAQ

What does the token-holder-analysis skill do?

Token holder distribution, concentration metrics, insider detection, and supply analysis for Solana tokens

How do I install token-holder-analysis?

Run npx skills add https://github.com/agiprolabs/claude-trading-skills --skill token-holder-analysis in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/token-holder-analysis/ (personal) or .claude/skills/token-holder-analysis/ (project).

Which AI agents can use token-holder-analysis?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is token-holder-analysis safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains token-holder-analysis?

It is published by agiprolabs in agiprolabs/claude-trading-skills. It has 436 recorded installs.

More from agiprolabs/claude-trading-skills

View all →

walk-forward-validation

agiprolabs/claude-trading-skills

Walk-forward validation framework for trading strategies and ML models with time-series-aware splits, overfit detection, and regime-aware validation

Business & Finance714 installs

risk-management

agiprolabs/claude-trading-skills

Portfolio-level risk controls, drawdown management, exposure limits, and circuit breakers for crypto trading

Business & Finance637 installs

pandas-ta

agiprolabs/claude-trading-skills

Technical analysis with 130+ indicators using pandas-ta for crypto market data

Data & Databases593 installs

position-sizing

agiprolabs/claude-trading-skills

Trade sizing methods including fixed fractional, volatility-adjusted, Kelly criterion, and liquidity-constrained sizing

Business & Finance581 installs

regime-detection

agiprolabs/claude-trading-skills

Market regime identification using volatility clustering, trend detection, and statistical methods for adaptive trading

Business & Finance578 installs

kelly-criterion

agiprolabs/claude-trading-skills

Kelly criterion optimal sizing with fractional variants, edge estimation, and practical application for crypto trading

Business & Finance534 installs

Popular business & finance skills

View category →

sales-enablement

coreyhaines31/marketingskills

When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also use when the user mentions 'sales deck,' 'pitch deck,' 'one-pager,' 'leave-behind,' 'objection handling,' 'deal-specific ROI analysis,' 'demo script,' 'talk track,' 'sales playbook,' 'proposal template,' 'buyer persona card,' 'battle card,' 'battlecard,' 'competitive one-pager,' 'win-loss analysis,' 'why are we losing deals,' 'loss reasons,' 'how do I respond to this objection,' 'prospect just said,' 'help my sales team,' 'sales materials,' or 'what should I give my sales reps,' 'cold call script,' or 'voicemail script.' Use this for any document or asset that helps a sales team close deals. For public competitor comparison pages, see competitors. For running buyer interviews or churn research, see customer-research. For marketing website copy, see copywriting. For cold outreach emails, see cold-email. For the offer being sold (bonuses, guarantees, pricing structure),

Business & Finance119.5K installs

revops

coreyhaines31/marketingskills

When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'outbound pipeline stages,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and processes that connect marketing to revenue. For cold outreach emails, see cold-email. For email drip campaigns, see emails. For pricing decisions, see pricing.

Business & Finance114.1K installs

sales-funnel-blueprint

autonnel/autonnel-skills

Turn an offer into a concrete multi-step sales funnel spec - page-by-page structure, price ladder, copy outline and the metrics each step must hit. Use when asked to build a sales funnel, marketing funnel, landing page flow, lead magnet funnel, webinar funnel, tripwire or VSL funnel, when planning a product launch page flow, or when someone asks "what pages do I need" for selling something online.

Business & Finance104.5K installs

pricing

coreyhaines31/marketingskills

When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' 'should I offer a free plan,' 'pricing page teardown,' 'pricing page audit,' 'is my pricing page AI-readable,' or 'can AI read my pricing.' Use this whenever someone is figuring out what to charge, how to structure their plans, or wants to audit a pricing page (for humans and for the AI agents that shortlist tools). For in-app upgrade screens, see paywalls. For offer construction (bonuses, guarantees, value framing, naming) on services/courses/coaching/high-ticket B2B, see offers.

Business & Finance80K installs

cross-border-ecommerce

nexscope-ai/ecommerce-skills

Cross-border e-commerce expansion advisor. Scores target markets on 8 weighted dimensions (market size, ecommerce penetration, competition, regulatory complexity, logistics infrastructure, payment ecosystem, cultural distance, IP protection), compares 5 fulfillment models with cost and transit data, provides country-by-country tax/duty compliance guides (EU VAT/IOSS, UK VAT, US sales tax, CA GST, AU GST, JP consumption tax), maps local payment preferences by market, and builds a phased expansion roadmap. No API key required.

Business & Finance62.9K installs

pricing-strategy

coreyhaines31/marketingskills

When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' or 'should I offer a free plan.' Use this whenever someone is figuring out what to charge or how to structure their plans. For in-app upgrade screens, see paywall-upgrade-cro.

Business & Finance61.2K installs