# Nansen Token Holders (TGM)

> Nansen Token Holders (TGM) is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.05/call, status unknown (last checked 2026-10-09).

Retrieves top token holders with balances, historical activity, balance changes, and smart money labels for any token across 26+ chains.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/tgm/holders?utm_source=zero.xyz
- Price: $0.05/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-09
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-holders-4212946e
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_KFd2dyBdsGzqbQJZFH-iB

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nansen-holders-4212946e -d '<json body>'
```

Example prompt: Show me the top smart money and whale holders of the USDC token on Ethereum, filtering for wallets holding at least $10,000 worth, and include their 7-day balance changes.

## When to prefer this

Use this endpoint when you need ranked token holder data with smart money labels, balance change history, and ownership percentages across major blockchains. Prefer over generic on-chain queries when you need Nansen's proprietary smart money and whale labeling. Best for token distribution analysis, whale watching, and tracking institutional/fund accumulation or distribution patterns.

## Known failure modes

- Invalid chain enum value — returns 422 validation error
- Token address not found on specified chain — returns empty data array
- Timeout when querying native tokens with all_holders label and unsupported filters — mitigated by using optimized model
- Unsupported filter fields when using all_holders label type on native tokens — returns error or warning
- Pagination out of range — returns empty data array
- Missing required fields (chain or token_address) — returns 422 validation error

## How this service works

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`):**
When omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.

## Output

Returns a paginated list of token holder records, each containing the holder's address, current token balance, USD value, ownership percentage of total supply, total inflow/outflow, 24h/7d/30d balance changes, and address label (e.g. 'Smart Money', 'Exchange', 'Whale'). Also includes optional warnings about query result quality.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMHoldersRequest",
 "required": [
  "chain",
  "token_address"
 ],
 "properties": {
  "chain": {
   "enum": [
    "arbitrum",
    "arc",
    "avalanche",
    "base",
    "bitcoin",
    "bnb",
    "ethereum",
    "hyperevm",
    "injective",
    "iotaevm",
    "linea",
    "mantle",
    "mantra",
    "monad",
    "near",
    "optimism",
    "plasma",
    "polygon",
    "robinhood",
    "sei",
    "solana",
    "sonic",
    "starknet",
    "sui",
    "ton",
    "tron"
   ],
   "type": "string",
   "title": "TGMHoldersChain",
   "description": "Chains supported for TGM holders endpoint."
  },
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "TGMHoldersFilters",
     "properties": {
      "address": {
       "anyOf": [
        {
         "type": "string"
        },
        {
         "type": "array",
         "items": {
          "type": "string"
         }
        },
        {
         "type": "null"
        }
       ],
       "title": "Address",
       "examples": [
        "0x28c6c06298d514db089934071355e5743bf21d60"
       ],
       "description": "Holder address filter"
      },
      "value_usd": {
       "anyOf": [
        {
         "type": "object",
         "title": "NumericRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Max",
           "examples": [
            50000,
            10000000,
            100
           ],
           "description": "Maximum value (inclusive)"
          },
          "min": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Min",
           "examples": [
            1000,
            1000000,
            -50,
            0
           ],
           "description": "Minimum value (inclusive)"
          }
         },
         "description": "Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"
        }
       ],
       "examples": [
        {
         "min": 10000
        }
       ],
       "description": "Balance range filter in USD. Defaults to min: 1.0 to exclude dust holders. Set explicitly to override (e.g., {\"min\": 0} to include all holders). Note: This default does not apply to native tokens with 'all_holders' label."
      },
      "token_amount": {
       "anyOf": [
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMHoldersResponse",
 "required": [
  "data",
  "pagination"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TGMHolder",
    "properties": {
     "address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address",
      "examples": [
       "0x1234567890123456789012345678901234567890"
      ],
      "description": "Address of contract/EOA"
     },
     "value_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Value Usd",
      "examples": [
       50000
      ],
      "description": "Current token balance value in USD"
     },
     "token_amount": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Token Amount",
      "examples": [
       1000000
      ],
      "description": "Total balance count"
     },
     "total_inflow": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Total Inflow",
      "examples": [
       1050000
      ],
      "description": "Total amount of tokens received by this address"
     },
     "address_label": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address Label",
      "examples": [
       "Smart Money"
      ],
      "description": "Label associated with the address"
     },
     "total_outflow": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Total Outflow",
      "examples": [
       50000
      ],
      "description": "Total amount of tokens sent by this address"
     },
     "balance_change_7d": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Balance Change 7D",
      "examples": [
       5000
      ],
      "description": "Token balance change over the last 7 days"
     },
     "balance_change_24h": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Balance Change 24H",
      "examples": [
       1000
      ],
      "description": "Token balance change over the last 24 hours"
     },
     "balance_change_30d": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Balance Change 30D",
      "examples": [
       15000
      ],
      "description": "Token balance change over the last 30 days"
     },
     "ownership_percentage": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
   
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-holders-4212946e/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)