Sign in

v1

latestOpenAPI 3.1.02026-07-2359362475.0 KB
Token God Mode

Get "Token God Mode" (TGM) holders data

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.

post/api/v1/tgm/holders

Request body

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_addressstring required

Token address

aggregate_by_entityboolean

Whether to return entity data

label_type'whale' | 'public_figure' | 'smart_money' | 'all_holders' | 'exchange'

TGM holders label types.

premium_labelsboolean

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.

Response

TGM holders data

warningsstring[]

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.