Holders
Authorizations
Body
Responses
200
Successful response
application/json
400
Bad request
application/json
401
Authentication error
application/json
403
Forbidden - Subscription tier required
application/json
500
Internal server error
application/json
post
POST /api/beta/tgm/holders HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 269
{
"parameters": {
"chain": "ethereum",
"tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"date": {
"from": "2025-05-01",
"to": "2025-05-03"
},
"isEntity": true,
"includeLabels": [],
"label": "top_100_holders",
"isStablecoin": false
},
"pagination": {
"page": 1,
"recordsPerPage": 100
}
}
[
{
"address": "text",
"name": "text",
"balance": "text",
"date": "text",
"sent": "text",
"received": "text",
"changeShortTimeframe": "text",
"changeMediumTimeframe": "text",
"changeLongTimeframe": "text",
"percentOwnership": "text",
"balanceUsd": 1,
"shortTimeframeHours": "text",
"mediumTimeframeHours": "text",
"longTimeframeHours": "text",
"costBasis": "text",
"realizedPnl": "text",
"unrealizedPnl": "text",
"sentCexPct": "text",
"receivedCexPct": "text",
"sentDexPct": "text",
"receivedDexPct": "text",
"sentContractPct": "text",
"receivedContractPct": "text",
"sentWalletPct": "text",
"receivedWalletPct": "text"
}
]
How to use the Holders Endpoint
The Holders Endpoint returns holder data for a given token on a specific chain over a defined date range. You can use this to analyze who is holding a particular token—whether it’s Smart Money wallets, exchanges, or all holders.
Usecase 1: Get list of Smart Money Holders
Set "label" to "smart_money" in the parameters object.
Add "includeLabels" as an array with the specific Smart Money segments you want (e.g., "Fund", "30D Smart Trader").
Other parameters (like chain, tokenAddress, date range, etc.) stay the same.
Example Configuration:
"label": "smart_money",
"includeLabels": ["Fund", "30D Smart Trader"]
"isEntity": true, -- To aggregate by Entity
Usecase 2: List of Exchanges Holding a Token
Set "label" to "exchange" in the parameters object.
Add "includeLabels" with "Exchange"
Other parameters remain unchanged.
Example Configuration:
"label": "exchange",
"includeLabels": ["Exchange"]
"isEntity": true, -- To aggregate by Entity
Last updated
Was this helpful?