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

400

Bad request

application/json

401

Authentication error

application/json

403

Forbidden - Subscription tier required

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

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