# Token Holder Tracker — Top Holders + Concentration % (`gochujang/token-holder-tracker`) Actor

Fetch top N holders for any ERC20 token: balance, % of supply, wallet age. Detect whale concentration, insider holdings, and supply distribution risk before trading. Supports any Ethereum token address. Ethplorer data. PPE $0.001/holder.

- **URL**: https://apify.com/gochujang/token-holder-tracker.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** Business
- **Features:** Limited permissions
- **Stats:** 3 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 holder trackeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Token Holder Tracker do?

The **token holder tracker** returns the top N holders of any Ethereum ERC-20 token — wallet address, balance, and percentage of total supply — alongside **crypto wallet distribution** metrics including top-10 and top-100 concentration percentages and total holder count. It accepts multiple contract addresses in a single run, making it ideal for batch due diligence workflows. Powered by Ethplorer's public API, no API key is required for standard usage.

In one API call, this Actor delivers the **top holders analytics** that would otherwise require running an Ethereum archive node or subscribing to a paid token data service.

### Why use Token Holder Tracker?

**1. Pre-trade whale due diligence**
Before entering any ERC-20 position, check whether top-10 holders control more than 50% of supply — a classic rug-pull concentration pattern. This Actor surfaces that metric in seconds, not hours of manual blockchain scanning.

**2. Whale accumulation and distribution alerts**
Schedule daily runs for tokens in your portfolio. When `top_10_share_pct` rises significantly day-over-day, that is whale accumulation absorbing sell pressure — often a bullish signal before a move.

**3. DAO governance health tracking**
For governance tokens, healthy DAOs show **crypto wallet distribution** that broadens over time. Track `top_100_share_pct` month-over-month to detect silent insider selling or concentration creep before it affects governance outcomes.

**4. CEX listing and airdrop verification**
After an exchange listing or airdrop event, holder counts should increase and top-holder concentration should decrease as supply distributes. Verify this actually happened using before/after snapshots.

**5. Memecoin and fair-launch risk scoring**
Build an automated filter: reject any token where `top_10_share_pct > 50`. Run the Actor as part of a multi-token sweep to screen 5–20 memecoins simultaneously with a single Actor run.

### How to use Token Holder Tracker

1. Open the Actor on Apify Store and click **Try for free**.
2. Provide one or more ERC-20 contract addresses in the `tokens` field.
3. Set `topN` to the number of holders you want returned per token (default 50, max 1000).
4. (Optional) Set `minSharePct` to skip dust holders below a percentage threshold.
5. Click **Start**. The Actor queries Ethplorer and returns per-holder rows plus a per-token `SUMMARY` with concentration metrics.

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `tokens` | string\[] | — | ERC-20 contract addresses (required) |
| `topN` | integer | `50` | Number of holders to return per token (5–1000) |
| `minSharePct` | number | `0` | Skip holders below this percentage of supply |
| `ethplorerApiKey` | string | `freekey` | Optional paid Ethplorer key for higher rate limits |

**Single token — PEPE whale watch:**

```json
{
  "tokens": ["0x6982508145454ce325ddbe47a25d4ec3d2311933"],
  "topN": 100,
  "minSharePct": 0.5
}
```

**Multi-token concentration sweep:**

```json
{
  "tokens": [
    "0x6982508145454ce325ddbe47a25d4ec3d2311933",
    "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
    "0x4d224452801ACEd8B2F0aebE155379bb5D594381"
  ],
  "topN": 20
}
```

### Output

One dataset row per holder:

```json
{
  "token_symbol": "PEPE",
  "token_name": "Pepe",
  "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "rank": 1,
  "holder_address": "0xf977814e90da44bfa03b6295a0616a897441acec",
  "balance": 56116400786424057000000.0,
  "share_pct": 13.34,
  "is_contract": null
}
```

A per-token `SUMMARY` record with **top holders analytics**:

```json
{
  "token_symbol": "PEPE",
  "total_holders": 555833,
  "top_10_share_pct": 51.42,
  "top_100_share_pct": 73.18,
  "holders_returned": 100
}
```

### Data fields

| Field | Description |
|-------|-------------|
| `rank` | Holder rank by balance (1 = largest holder) |
| `holder_address` | Ethereum wallet or contract address |
| `balance` | Token balance in native units |
| `share_pct` | Holder's percentage of total token supply |
| `is_contract` | Whether the address is a smart contract (CEX, protocol, etc.) |
| `total_holders` | Total number of addresses holding any balance |
| `top_10_share_pct` | Percentage of supply controlled by the top 10 holders |
| `top_100_share_pct` | Percentage of supply controlled by the top 100 holders |

### Cost estimation

This Actor uses **Pay-Per-Event (PPE)** pricing:

| Scenario | Holders returned | Estimated Cost |
|----------|-----------------|----------------|
| Top 50 for 1 token | 50 | $0.05 |
| Top 100 for 1 token | 100 | $0.10 |
| Top 100 for 5 tokens | 500 | $0.50 |
| Daily monitoring (5 tokens × top 50) | 250/day | ~$7.50/month |

Rate: **$0.001 per holder row returned**.

### FAQ

**Q: Does this support tokens on chains other than Ethereum?**
Currently Ethereum mainnet only. ERC-20 contracts on other EVM chains (Arbitrum, Base, Polygon) are not supported in the current version.

**Q: What are the rate limits on the free Ethplorer key?**
The default `freekey` has rate limits suitable for small to medium batch sizes. For production-scale sweeps (50+ tokens per run), provide your own Ethplorer API key via the `ethplorerApiKey` field to avoid throttling.

**Q: Why is `is_contract` sometimes null?**
The free Ethplorer API tier does not reliably populate this field. For contract classification (e.g., identifying CEX wallets), cross-reference the `holder_address` against on-chain label databases or the CEX Reserve Tracker Actor.

***

**Disclaimer:** Data sourced from Ethplorer's public API. Ethereum mainnet only. Not affiliated with Ethplorer. Not financial or investment advice. **Top holders analytics** are provided for informational and research purposes.

**Keywords:** token holder tracker, crypto wallet distribution, top holders analytics, ERC-20 holder analysis, whale concentration, token due diligence, holder count Ethereum, whale detection crypto, token supply distribution

***

### Related actors

- [Smart Money Wallet Tracker](https://apify.com/gochujang/smart-money-wallet-tracker) — Track on-chain activity of top holders identified by this actor
- [DeFi Hack Monitor](https://apify.com/gochujang/defi-hack-monitor) — Security context for tokens with abnormal holder concentration changes
- [Crypto Alpha Dashboard](https://apify.com/gochujang/crypto-alpha-dashboard) — Combine token holder data with price momentum for full due diligence

### Feedback

If this actor helps your token research, a review helps others find it: [Leave a review on Apify Store](https://apify.com/gochujang/token-holder-tracker#reviews)

# Actor input Schema

## `tokens` (type: `array`):

ERC-20 contract addresses to query. Each address consumes one query.

## `topN` (type: `integer`):

Number of top holders to fetch per token (max 1000 due to Ethplorer free tier).

## `minSharePct` (type: `number`):

Skip holders whose share is below this %. 0 = include all.

## `ethplorerApiKey` (type: `string`):

Bring your own Ethplorer API key for higher rate limits. Leave empty to use the free shared key (slower).

## `fetchWhaleHistory` (type: `boolean`):

Optional parameter: fetchWhaleHistory

## Actor input object example

```json
{
  "tokens": [
    "0x6982508145454ce325ddbe47a25d4ec3d2311933"
  ],
  "topN": 50,
  "minSharePct": 0
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "tokens": [
        "0x6982508145454ce325ddbe47a25d4ec3d2311933"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/token-holder-tracker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "tokens": ["0x6982508145454ce325ddbe47a25d4ec3d2311933"] }

# Run the Actor and wait for it to finish
run = client.actor("gochujang/token-holder-tracker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "tokens": [
    "0x6982508145454ce325ddbe47a25d4ec3d2311933"
  ]
}' |
apify call gochujang/token-holder-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gochujang/token-holder-tracker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MxXVagBuJwNsdXkb8/builds/BI2mVr5JmzE6wbGsJ/openapi.json