HolderScan API - Token Holder Data for Developers and AI Agents

HolderScan tracks token holders across Solana and Ethereum. The HolderScan API gives you programmatic access to the same data: holder counts, holder changes, distribution metrics, average hold time, PnL, wallet categories, and more. It is a REST API that returns JSON.

This article covers what data is available, how to use each endpoint, and practical examples for developers building trading tools, analytics dashboards, or AI agents that need on-chain holder data.

What Data Can You Get?

The API covers six areas of token holder analytics:

• Token lookup - search and retrieve tokens tracked on HolderScan
• Holder counts and lists - get the current number of holders for any token, or list individual holder wallets with amounts and ranks
• Holder changes over time - see how holder count changed in the last hour, day, week, or month
• Holder breakdown by USD value - categorize holders into Shrimp, Crab, Fish, Dolphin, and Whale tiers, plus counts of holders over $10, $100, $1K, $10K, $100K, and $1M
• Distribution and concentration - Gini coefficient, HHI, median holder position, average hold time, and retention rate
• Advanced wallet analytics - PnL (realized and unrealized), holding duration breakdown (Diamond, Gold, Silver, Bronze, Wood hands), and per-wallet statistics

How to Get Solana Token Holder Count

To get the current holder count for a Solana token, call the holders endpoint with the token's contract address:

GET https://api.holderscan.com/v0/sol/tokens/{token_address}/holders

# Example: Get holder count for a Solana token
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.holderscan.com/v0/sol/tokens/So11111111111111111111111111111111111111112/holders?limit=1

The response includes the total holder count along with the holder list:

{
  "holder_count" 52847,
  "total" 52847,
  "holders" [
    {
      "address" "5Q544fK...",
      "amount" 1250000.50,
      "rank" 1,
      "spl_token_account" "7Yh3Z..."
    }
  ]
}

The same endpoint works for Ethereum tokens by replacing sol with eth in the URL.

How to Get Holder Count Changes Over Time

The holder deltas endpoint returns how much the holder count changed across multiple timeframes, from 1 hour to 30 days:

GET https://api.holderscan.com/v0/sol/tokens/{token_address}/holders/deltas

{
  "1hour" 23,
  "2hours" 41,
  "4hours" 78,
  "12hours" 156,
  "1day" 312,
  "3days" 890,
  "7days" 2100,
  "14days" 3500,
  "30days" 8200
}

A sudden spike in 1-hour or 4-hour deltas can signal organic interest or bot activity. Comparing short-term and long-term deltas helps distinguish between lasting growth and temporary spikes.

How to Get Average Hold Time for Token Holders

Average hold time tells you how long holders have been keeping their tokens. This is one of the few metrics that separates conviction from speculation. The stats endpoint returns it alongside other distribution metrics:

GET https://api.holderscan.com/v0/sol/tokens/{token_address}/stats

{
  "hhi" 55,
  "gini" 0.959,
  "median_holder_position" 56,
  "avg_time_held" 42.5,
  "retention_rate" 0.73
}

A higher average hold time suggests holders are not just flipping the token. Combined with the retention rate, you can tell whether a token has a sticky holder base or one that churns quickly.

Token Holder Distribution and Concentration Metrics

The same stats endpoint returns distribution metrics that measure how concentrated a token's supply is:

• HHI (Herfindahl-Hirschman Index) - measures how much the largest holders dominate. Ranges from 0 (perfectly spread) to 10,000 (single holder). Below 100 is considered low concentration.
• Gini coefficient - measures inequality across all holders. Closer to 1 means more unequal. Most tokens are above 0.9.
• Median holder position - the rank at which half the supply is accounted for. Lower means more concentrated at the top.
• Retention rate - what fraction of holders that bought the token still hold it.

Holder Breakdown by USD Value

The breakdowns endpoint categorizes every holder by the USD value of their position:

GET https://api.holderscan.com/v0/sol/tokens/{token_address}/holders/breakdowns

{
  "total_holders" 52847,
  "holders_over_10_usd" 28400,
  "holders_over_100_usd" 12300,
  "holders_over_1000_usd" 3100,
  "holders_over_10000_usd" 420,
  "holders_over_100k_usd" 35,
  "holders_over_1m_usd" 4,
  "categories" {
    "shrimp" 24447,
    "crab" 16100,
    "fish" 9200,
    "dolphin" 2680,
    "whale" 420
  }
}

If you want to know how many wallets hold more than $1,000 worth of a Solana token, this is the endpoint. It is also useful for filtering out dust wallets - a token might show 50,000 holders, but only 12,000 hold more than $100.

PnL Data for Token Holders

The PnL endpoint returns aggregate profit and loss data based on the top 1,000 holders:

GET https://api.holderscan.com/v0/sol/tokens/{token_address}/stats/pnl

{
  "break_even_price" 0.0234,
  "realized_pnl_total" 1250000,
  "unrealized_pnl_total" 3400000
}

This tells you the average cost basis and whether the largest holders are sitting on profit or loss. If unrealized PnL is highly negative, large holders may be underwater and less likely to sell. If it is highly positive, there is profit-taking risk.

Diamond Hands vs Paper Hands - Supply Breakdown

The supply breakdown endpoint shows what fraction of the token supply is held by wallets grouped by holding duration:

GET https://api.holderscan.com/v0/sol/tokens/{token_address}/stats/supply-breakdown

{
  "diamond" 0.45,
  "gold" 0.12,
  "silver" 0.08,
  "bronze" 0.15,
  "wood" 0.20
}

• Diamond - held over 90 days
• Gold - held 60 to 90 days
• Silver - held 30 to 60 days
• Bronze - held 15 to 30 days
• Wood - held under 15 days

A token where 45% of supply is diamond hands is very different from one where 80% is wood. This metric helps assess whether holders have conviction or are short-term speculators.

Per-Wallet Holder Statistics

You can get detailed analytics for any specific wallet's holding of a token:

GET https://api.holderscan.com/v0/sol/tokens/{token_address}/stats/{wallet_address}

{
  "amount" 50000,
  "avg_time_held" 67.3,
  "holder_category" "dolphin",
  "holding_breakdown" {
    "diamond" 30000,
    "gold" 10000,
    "silver" 5000,
    "bronze" 3000,
    "wood" 2000
  },
  "unrealized_pnl" 12500,
  "realized_pnl" 3200
}

This is useful for building wallet tracking tools or analyzing specific whale wallets. The FIFO-based holding breakdown shows exactly how much of the wallet's position is long-term vs recently acquired.

Use Cases

Trading Bots and Automated Strategies

Use holder deltas and PnL data to build signals. A token gaining 500 holders per day with rising average hold time looks different from one gaining the same number but with increasing wood-hand percentage. Combine holder data with price data to create strategies that go beyond simple technical analysis.

AI Agents and LLMs

AI agents that analyze crypto tokens can use the HolderScan API to answer questions like "How many people hold this token?", "What is the average hold time?", or "What percentage of holders are in profit?" The API returns structured JSON that is easy to parse in any agent framework. Instead of scraping websites or interpreting charts, an LLM can call a single endpoint and get a direct answer.

Analytics Dashboards

Build custom dashboards that combine HolderScan data with other data sources. Track holder concentration risk across your portfolio, monitor whale movements in real time, or build screening tools that filter tokens by distribution quality.

Due Diligence and Research

Funds and research teams can use distribution metrics (HHI, Gini) to assess concentration risk before investing. The holder breakdown by USD value helps identify whether a token has real economic participation or is mostly dust wallets.

Supported Chains

The API currently supports Solana and Ethereum tokens. Use sol or eth as the chain identifier in any endpoint URL. Only tokens that are listed on HolderScan are available through the API.

Getting Started

Sign up for an API key on the API Plans page. The Standard tier is included with HolderScan Premium. Full endpoint documentation is available at docs.holderscan.com.

Frequently Asked Questions

How do I get Solana token holder counts via API?

Call GET /v0/sol/tokens/{address}/holders with your API key. The response includes holder_count with the current total. You can also filter holders by min_amount and max_amount to exclude dust wallets.

How do I get Ethereum token holder data via API?

Use the same endpoints as Solana but replace sol with eth in the URL. For example: GET /v0/eth/tokens/{address}/holders.

How do I get average hold time for token holders?

The /stats endpoint returns avg_time_held for any token. For per-wallet hold time, use /stats/{wallet_address}. Hold time is calculated using FIFO based on actual transaction history.

What is the best API for token holder analytics?

HolderScan is purpose-built for holder analytics. Unlike general blockchain APIs that return raw account data, HolderScan provides computed metrics like average hold time, holder categories (Diamond/Gold/Silver/Bronze/Wood), PnL per wallet, distribution scores, and holder breakdowns by USD value. No need to process raw transactions yourself.

Can I use this API with AI agents or LLMs?

Yes. The API returns structured JSON that works with any AI framework. You can use it as a tool in LangChain, CrewAI, or any agent that supports HTTP tool calling. The responses are concise and designed to be directly interpretable without additional processing.

How much does the token holder API cost?

The Standard tier is included with HolderScan Premium (200,000 request units/month). Paid tiers start at $149/month for 15 million request units. See the API Plans page for full pricing.

What is the rate limit?

Rate limits depend on your plan: 300 requests per minute on Standard, up to 2,500 on Enterprise. Each endpoint consumes a different number of request units based on data complexity.