---
title: "Get \"Token God Mode\" (TGM) holders data"
method: POST
path: "/api/v1/tgm/holders"
tags: ["Token God Mode"]
---

# Get "Token God Mode" (TGM) holders data

`POST /api/v1/tgm/holders`

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.

## Request body

- TGMHoldersRequest — 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.
  - `chain` 'arbitrum' | 'avalanche' | 'base' | 'bitcoin' | 'bnb' | 'ethereum' | 'hyperevm' | 'injective' | 'iotaevm' | 'linea' | 'mantle' | 'mantra' | 'monad' | 'near' | 'optimism' | 'plasma' | 'polygon' | 'robinhood' | 'sei' | 'solana' | 'sonic' | 'starknet' | 'sui' | 'ton' | 'tron', required — Chains supported for TGM holders endpoint.
  - `token_address` string, required — Token address
  - `aggregate_by_entity` boolean — Whether to return entity data
  - `label_type` 'whale' | 'public_figure' | 'smart_money' | 'all_holders' | 'exchange' — TGM holders label types.
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` TGMHoldersFilters — Filters for TGM holders endpoint. These filters control which holders are included in the analysis.
    - `include_smart_money_labels` LabelType[] — Include smart money labels for holders
    - `exclude_smart_money_labels` LabelType[] — Exclude smart money labels for holders
    - `address` union — Holder address filter
      - string
      - string[]
    - `address_label` union — Holder label filter
      - string
      - string[]
    - `token_amount` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `total_outflow` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `total_inflow` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `balance_change_24h` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `balance_change_7d` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `balance_change_30d` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `ownership_percentage` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `value_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
  - `premium_labels` boolean — Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan.
  - `order_by` SortOrderTGMHoldersSortField[] — 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
    - `field` 'address' | 'name' | 'token_amount' | 'total_outflow' | 'total_inflow' | 'balance_change_24h' | 'balance_change_7d' | 'balance_change_30d' | 'ownership_percentage' | 'value_usd', required — Enum for sortable fields in TGM holders.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

TGM holders data

- TGMHoldersResponse — Response model for TGM holders endpoint. Contains a list of holder records with pagination and metadata.
  - `data` TGMHolder[], required — List of TGM holder records
    - `address` string — Address of contract/EOA
    - `address_label` string — Label associated with the address
    - `token_amount` number — Total balance count
    - `total_outflow` number — Total amount of tokens sent by this address
    - `total_inflow` number — Total amount of tokens received by this address
    - `balance_change_24h` number — Token balance change over the last 24 hours
    - `balance_change_7d` number — Token balance change over the last 7 days
    - `balance_change_30d` number — Token balance change over the last 30 days
    - `ownership_percentage` number — Percentage of total token supply owned by this address
    - `value_usd` number — Current token balance value in USD
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page
  - `warnings` string[] — Optional warnings about the query results. For example, if a token has no USD price data, a warning will indicate that the default value_usd filter may be excluding results.

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)