Holders

Update: A premium_labels parameter is being added to this endpoint. From April 1, the default changes from true to false .

Get TGM Holders Data

post

Retrieve the top token holders with their current balances, historical activity, and recent balance changes. Provides insights into token distribution, smart money and fund holdings.

Performance Optimization for Native Tokens: When querying native tokens with label_type: "all_holders", this endpoint uses an optimized model to prevent timeouts. This optimization has the following limitations:

• Ordering: Only token_amount field is supported

• Filters: Limited to: token_amount, total_outflow, total_inflow, address, include_smart_money_labels, exclude_smart_money_labels

To use advanced filters and ordering on native tokens, specify a label_type other than "all_holders" (e.g., "smart_money", "whale", "exchange").

Label Tier Control (premium_labels): The premium_labels parameter is now available to all users. When omitted, it defaults to true (premium labels). In a future release, the default will change to false. Pass premium_labels=true explicitly to preserve premium label behavior.

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for TGM holders endpoint.

This endpoint provides comprehensive data on token holders and their balances. Retrieve holders by various criteria including smart money, exchanges, public figures, whales, and top holders with detailed balance information and filtering options.

chainstring · enumRequired

Blockchain chain

Example: solanaPossible values:

token_addressstringRequired

Token address

Example: 2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv

aggregate_by_entitybooleanOptional

Whether to return entity data

Default: false

label_typestring · enumOptional

Label type. You must also include the labels filter to match the label type. For example, for label type 'smart_money', you must include '30D Smart Trader', '90D Smart Trader', '180D Smart Trader', 'Fund' or 'Smart Trader' in the filters.labels.include parameter.

Default: all_holdersExample: all_holdersPossible values:

filtersany ofOptional

Additional filters to apply to the query.

Example: {"include_smart_money_labels":["30D Smart Trader","Fund"],"ownership_percentage":{"min":0.01},"token_amount":{"min":1000},"value_usd":{"min":10000}}

premium_labelsany ofOptional

Controls label tier in the response. When null/omitted, defaults to true (premium labels filtered by subscription plan). When false, returns free-tier labels for all users. When true, returns premium labels (filtered by subscription plan). Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.

booleanOptional

order_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

• [{"field": "value_usd", "direction": "DESC"}] - Sort by value USD descending
• [{"field": "token_amount", "direction": "ASC"}] - Sort by token amount ascending
• [{"field": "ownership_percentage", "direction": "DESC"}] - Sort by ownership percentage descending

Responses

200

TGM holders data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

402

Payment Required

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/holders

HTTPcURLJavaScriptPython

POST /api/v1/tgm/holders HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 406

{
  "chain": "solana",
  "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
  "aggregate_by_entity": false,
  "label_type": "all_holders",
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "include_smart_money_labels": [
      "30D Smart Trader",
      "Fund"
    ],
    "ownership_percentage": {
      "min": 0.01
    },
    "token_amount": {
      "min": 1000
    },
    "value_usd": {
      "min": 10000
    }
  },
  "premium_labels": true,
  "order_by": [
    {
      "field": "address",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "address": "0x1234567890123456789012345678901234567890",
      "address_label": "Smart Money",
      "token_amount": 1000000,
      "total_outflow": 50000,
      "total_inflow": 1050000,
      "balance_change_24h": 1000,
      "balance_change_7d": 5000,
      "balance_change_30d": 15000,
      "ownership_percentage": 2.5,
      "value_usd": 50000
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "warnings": [
    "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