Retrieve top token holders by entity category with balance changes, inflows, and ownership data.
What it does
The Nansen TGM Holders endpoint (`/api/v1/tgm/holders`) returns the top token holders for a given token on a specified chain, with current balances, historical balance changes (24h, 7d, 30d), inflow/outflow totals, and ownership percentages. Holders can be filtered by entity category — smart money, whales, exchanges, public figures, or all holders — and further refined with smart money label includes/excludes, address filters, balance range filters, and value-in-USD thresholds. Results can be aggregated by entity and sorted by fields like value_usd, token_amount, or ownership_percentage. Premium labels (smart money, alpha trader) are available via the `premium_labels` parameter.
The endpoint is a POST accepting a JSON body with `chain`, `token_address`, optional `label_type`, `filters`, `pagination`, `order_by`, and `premium_labels`. It supports 25+ chains including Ethereum, Solana, Base, Arbitrum, BNB, Polygon, and more. Pricing is $0.05 per call via the x402 protocol, or 50 credits (free tier) / 5 credits (pro tier) when using API-key billing. Premium label queries cost 150 pro credits. Rate limits are exposed via response headers. The endpoint returns paginated holder records with address, label, token_amount, value_usd, balance_change_24h/7d/30d, total_inflow, total_outflow, and ownership_percentage fields.
Capabilities
Use cases
- —Identify which smart money wallets or funds hold a specific token and track their balance changes
- —Monitor exchange inflows/outflows for a token to detect accumulation or distribution patterns
- —Analyze token ownership concentration by checking top holder percentages
- —Filter holders by entity category (whale, exchange, public figure) to understand holder composition
- —Track 24h/7d/30d balance changes of top holders to detect emerging trends
Fit
Best for
- —Blockchain analysts tracking smart money and whale token positions
- —Trading bots monitoring holder distribution shifts for signal generation
- —DeFi researchers analyzing token ownership concentration across chains
- —Portfolio managers evaluating token holder quality before investment decisions
Not for
- —Historical holder snapshots over time (use TGM Flows or historical holdings endpoints instead)
- —NFT holder analysis
- —Real-time sub-second holder tracking
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/holders \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"chain": "ethereum",
"token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
"label_type": "smart_money",
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"chain": "ethereum",
"filters": {
"value_usd": {
"min": 10000
},
"token_amount": {
"min": 1000
},
"include_smart_money_labels": [
"Fund",
"Smart Trader"
]
},
"order_by": [
{
"field": "value_usd",
"direction": "DESC"
}
],
"label_type": "smart_money",
"pagination": {
"page": 1,
"per_page": 10
},
"token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"
}Response
{
"data": [
{
"address": "0x1234567890123456789012345678901234567890",
"value_usd": 150000,
"token_amount": 50000,
"total_inflow": 52000,
"address_label": "Smart Money Fund",
"total_outflow": 2000,
"balance_change_7d": 5000,
"balance_change_24h": 1000,
"balance_change_30d": 15000,
"ownership_percentage": 0.33
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear endpoint description, x402 pricing ($0.05/call), and credit costs documented. The 402 probe confirms the endpoint is live. No crawled external docs beyond the OpenAPI spec, but the spec itself is comprehensive with filter enums, sort fields, and examples.
Warnings
- —No standalone documentation pages were reachable (docs/pricing/README all returned 404); all information derived from OpenAPI spec.
- —Response schema references TGMHoldersResponse but full field-level examples are inferred from the schema definitions, not from a live response sample.
Citations
- —Endpoint is POST /api/v1/tgm/holders under the Token God Mode taghttps://api.nansen.ai
- —x402 fixed price of $0.05 per call; credit costs are 50 (free) / 5 (pro), with premium_labels=true costing 150 pro creditshttps://api.nansen.ai
- —Supports 25+ chains including ethereum, solana, base, arbitrum, bnb, polygon, bitcoin, etc.https://api.nansen.ai
- —Label types include whale, public_figure, smart_money, all_holders, exchangehttps://api.nansen.ai
- —Endpoint returns 402 on HEAD probe confirming it is live via MPP protocolhttps://api.nansen.ai/api/v1/tgm/holders