# Nansen Token God Mode (TGM) Holders

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

Retrieves holders data for a specific token using Nansen's Token God Mode analytics, including wallet labels, smart money flags, and entity aggregations

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1/tgm/holders
- Price: $0.05/call
- Payment: MPP, x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/api-nansen-ai-947121b8
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_W3hjcJSVuU1RkjezPXMPU

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 api-nansen-ai-947121b8
```

Example prompt: Using Nansen Token God Mode, show me the top holders of token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum, grouped by entity, and filter to premium-labeled wallets only.

## When to prefer this

Use this endpoint when you need to identify who holds a specific token with the context of Nansen's proprietary wallet labels (smart money, exchanges, funds, whales). Prefer this over generic on-chain holder lookups when label intelligence, entity aggregation, or smart money classification is needed. Ideal for due diligence, market research, or monitoring institutional accumulation patterns.

## Known failure modes

- Invalid or unsupported token address returns 400 or empty result
- Unsupported chain value returns an error
- Malformed filters object causes 400 bad request
- Missing required token_address parameter causes request failure
- Payment failure (402) if x402 payment is not properly attached
- Rate limiting or quota exhaustion returns 429

## How this service works

Get "Token God Mode" (TGM) holders data

## Output

Returns a list of token holders with Nansen wallet labels (e.g. smart money, exchange, fund), optional entity aggregations, balances, label types, and metadata — filtered and sorted according to the query parameters.

## Example request

```json
{
 "chain": "ethereum",
 "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMHoldersRequest",
 "required": [
  "chain",
  "token_address"
 ],
 "properties": {
  "chain": {
   "enum": [
    "arbitrum",
    "avalanche",
    "base",
    "bitcoin",
    "bnb",
    "ethereum",
    "hyperevm",
    "injective",
    "iotaevm",
    "linea",
    "mantle",
    "mantra",
    "monad",
    "near",
    "optimism",
    "plasma",
    "polygon",
    "ronin",
    "scroll",
    "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/api-nansen-ai-947121b8/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)