# ERC-20 Token Intelligence & Holder Concentration Analysis (`centorprat/erc20-token-intelligence`) Actor

Give ERC-20 token contract addresses. Reads the public chain (keyless) and returns a token brief: identity, price + market cap + change, holders count, top holders, a holder-concentration analysis (burned supply excluded), and recent transfers. Read-only, agent-callable.

- **URL**: https://apify.com/centorprat/erc20-token-intelligence.md
- **Developed by:** [Centor Prat](https://apify.com/centorprat) (community)
- **Categories:** Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $17.00 / 1,000 token analyzeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## ERC-20 Token Intelligence & Holder Concentration Analysis

Due-diligence brief for any ERC-20 token. Give one or more token **contract addresses** and get back identity, market data (price, market cap, 24h/7d change), total holders, the **top holders with their share**, and a **holder-concentration analysis** — how much of the circulating supply a handful of wallets control, with burned supply separated out. Keyless, read-only, public chain only — agent-callable.

For token due diligence, crypto research, risk/rug screening, dashboards, and AI agents evaluating a token.

### What it does

- Reads public chain data via the keyless Ethplorer API — no key to manage.
- Pulls token identity + supply, live **price / market cap / change**, and **holders count**.
- Ranks the **top holders** and computes **concentration**: top-1, top-10 and top-50 combined share.
- **Separates burned supply** — burn/null addresses (0x…dead, 0x000…0) are removed supply, not holder control, so they don't inflate the concentration read (they're reported as `burnedShare`).
- Emits a concentration **signal** (broadly-distributed → concentrated → highly-concentrated → extreme) as a due-diligence read.

| Output field | Meaning |
|---|---|
| `name` / `symbol` / `decimals` / `totalSupply` | token identity |
| `priceUsd` / `marketCapUsd` / `priceDiff24h` / `priceDiff7d` | market |
| `holdersCount` | total holders |
| `topHolders[]` | address, `share` %, `balance`, `isBurnAddress` |
| `concentration` | `top1Share`, `top10Share`, `top50Share`, `burnedShare`, `holdersSampled` |
| `concentrationSignal` | broadly-distributed / concentrated / highly-concentrated / extreme-concentration |

### Why not just ask an AI agent?

An agent can look up one token's price. The **concentration analysis** — pulling the top holders, excluding burn addresses, and computing how much of the real circulating supply a few wallets control — is the non-obvious due-diligence layer most people wouldn't think to compute, done here deterministically and at batch scale.

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `tokens` | array of strings | ✅ | ERC-20 contract addresses (0x…). |
| `topHolders` | integer (1–100) | | How many top holders to list (concentration uses up to 50). |
| `webhookUrl` | string | | POST the finished briefs here as JSON. |

**Example input**

```json
{
  "tokens": [
    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE"
  ]
}
```

### Output

One record per token. **Example output** (SHIB, trimmed, real run):

```json
{
  "symbol": "SHIB",
  "name": "Shiba Inu",
  "totalSupply": 999982329050358.5,
  "holdersCount": 1697989,
  "priceUsd": 5.06e-06,
  "marketCapUsd": 2979275090.28,
  "priceDiff24h": -1.24,
  "concentrationSignal": "broadly-distributed",
  "concentration": {
    "top1Share": 6.39, "top10Share": 22.7, "top50Share": 36.43,
    "burnedShare": 41.04, "holdersSampled": 49,
    "note": "Top 10 holders control ~22.7% of the sampled supply (of 1697989 total holders)."
  },
  "topHolders": [
    {"address": "0xdead00...942069", "share": 41.04, "isBurnAddress": true}
  ]
}
```

### Use cases

- **Token due diligence / rug screening** — is the supply concentrated in a few wallets?
- **Research & dashboards** — identity, price, market cap and holder distribution in one call.
- **Portfolio risk** — flag concentrated holdings before buying.
- **AI agents** — a structured token brief + concentration signal to gate a decision.

### Ready-made tasks

- [Token Holder Concentration - Top 1/10/50 Share](https://apify.com/centorprat/erc20-token-intelligence/examples/token-holder-concentration)
- [ERC-20 Token Analysis - Price, Holders & Supply](https://apify.com/centorprat/erc20-token-intelligence/examples/erc20-token-analysis)
- [Top Token Holders List - ERC-20](https://apify.com/centorprat/erc20-token-intelligence/examples/top-token-holders-list)

### For AI agents / MCP

```
https://mcp.apify.com/?tools=actors,docs,centorprat/erc20-token-intelligence
```

Loads as `centorprat--erc20-token-intelligence`. Claude Code:

```
claude mcp add apify -- npx -y @apify/actors-mcp-server --actors centorprat/erc20-token-intelligence
```

### Alerts / scheduling

Set `webhookUrl` and schedule to re-check a token — holder concentration and market cap shift over time; the fresh brief is POSTed to Make/Zapier/your endpoint.

### FAQ

**Which chain?** Ethereum mainnet ERC-20 tokens (by contract address).

**Does it need a key?** No — keyless public API.

**What does "broadly-distributed" vs "concentrated" mean?** A read on how much of the circulating supply (burn addresses excluded) the top 10 holders control — a due-diligence signal, not a verdict that a token is safe or a scam.

**Why is a burn address the top holder?** Many tokens send supply to a burn address (0x…dead). That's removed from circulation, so it's reported as `burnedShare` and excluded from the concentration signal, with `isBurnAddress: true` on the holder.

**Are top holders individuals?** Often not — they're frequently exchanges, bridges or contracts. Treat concentration as a signal to investigate, not proof of control by one party.

**Are USD values exact?** Indicative market rates at check time.

**Cost?** Pay-per-event, one charge per token successfully analyzed.

### Data & attribution

Public Ethereum chain data via the keyless Ethplorer API; USD values are indicative. No keys, no personal data. Signals, not financial advice.

### Related actors

- [Crypto Address Risk & AML Screener](https://apify.com/centorprat/crypto-address-risk-aml-screener)
- [Ethereum Wallet & Token Tracer](https://apify.com/centorprat/ethereum-wallet-token-tracer)
- [Ethereum Address Monitor & Alert](https://apify.com/centorprat/ethereum-address-monitor-alert)

# Actor input Schema

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

ERC-20 token contract addresses (0x...). One intelligence brief per token.

## `topHolders` (type: `integer`):

How many top holders to return per token (concentration is always computed from up to 50).

## `webhookUrl` (type: `string`):

If set, the finished token briefs are POSTed here as JSON when the run completes.

## Actor input object example

```json
{
  "tokens": [
    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE"
  ],
  "topHolders": 10
}
```

# Actor output Schema

## `tokens` (type: `string`):

One brief per token: name/symbol/decimals/supply, holders count, price + market cap + 24h/7d change, top holders with share, a holder-concentration analysis (top-1/top-10/top-50 share, burned share, a concentration signal), and recent transfers.

# 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": [
        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE"
    ],
    "topHolders": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("centorprat/erc20-token-intelligence").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": [
        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
    ],
    "topHolders": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("centorprat/erc20-token-intelligence").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": [
    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE"
  ],
  "topHolders": 10
}' |
apify call centorprat/erc20-token-intelligence --silent --output-dataset

```

## MCP server setup

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

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/QPBuDVi4Jppld64eu/builds/UGI0ydLgdKJ8YN7Pd/openapi.json
