Holders

tgm/holders

post

This model shows the balance changes over a year for the current top 5 holders of the token.

Questions

  1. Who are the top holders for the given token?

  2. How did the top holders accumulate the tokens?

  3. What are the top holders doing with their tokens at the moment?

Authorizations
Body
Responses
200
Successful response
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

  1. Set "label" to "smart_money" in the parameters object.

  2. Add "includeLabels" as an array with the specific Smart Money segments you want (e.g., "Fund", "30D Smart Trader").

  3. 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

  1. Set "label" to "exchange" in the parameters object.

  2. Add "includeLabels" with "Exchange"

  3. Other parameters remain unchanged.

Example Configuration:

"label": "exchange",
"includeLabels": ["Exchange"]
"isEntity": true, -- To aggregate by Entity

Last updated

Was this helpful?