x402basequality 0.92

Retrieve top token holders with balances, activity, and smart money labels via Nansen's on-chain analytics API.

Price
per_call
Protocol
x402
Verified
no
Endpoint
https://api.nansen.ai/api/v1/tgm/holders

What it does

The Nansen TGM Holders endpoint (`POST /api/v1/tgm/holders`) returns the top holders of any token across 25+ blockchains, including current balances, 24h/7d/30d balance changes, total inflows/outflows, ownership percentages, and USD valuations. Results can be filtered by holder category (smart money, whales, exchanges, public figures, or all holders) and by smart money label sub-types such as Fund, Smart Trader, or 30D Smart Trader. The endpoint supports premium label tiers, pagination up to 1,000 rows per page, and flexible sort ordering.

This endpoint is part of Nansen's Token God Mode (TGM) suite and is payable per-call via the x402 protocol at $0.05 per request. It also supports traditional API-key authentication with a credit-based system (50 credits on the free tier, 5 on pro). The response includes rate-limit headers and credit-usage tracking. Native tokens queried with `label_type: "all_holders"` use an optimized model with limited filter/sort options to prevent timeouts.

The API is documented via a full OpenAPI 3.1 spec served at `api.nansen.ai`. Supported chains include Ethereum, Solana, Base, Arbitrum, BNB, Polygon, Bitcoin, Sui, Tron, and many more. Filters include address, token amount ranges, balance change ranges, ownership percentage, value in USD, and smart money label inclusion/exclusion.

Capabilities

token-holderssmart-money-labelsmulti-chainon-chain-analyticswallet-profilingbalance-trackingx402-paymentpaginationsort-orderinglabel-filtering

Use cases

  • —Identify which smart money wallets are accumulating or distributing a specific token
  • —Analyze token holder concentration and ownership distribution across chains
  • —Monitor 24h/7d/30d balance changes of top holders for trading signals
  • —Filter holders by label type (whale, exchange, smart money) for due diligence
  • —Build dashboards showing real-time holder composition for any ERC-20 or SPL token

Fit

Best for

  • —Crypto traders tracking smart money accumulation patterns
  • —Research analysts studying token holder distribution
  • —DeFi protocols monitoring their token's holder base
  • —Agents needing per-call blockchain analytics without subscriptions

Not for

  • —Historical holder snapshots over time (use /smart-money/historical-holdings instead)
  • —Non-blockchain or non-crypto data needs
  • —Free high-volume usage — each call costs $0.05 via x402

Quick start

curl -X POST https://api.nansen.ai/api/v1/tgm/holders \
  -H 'Content-Type: application/json' \
  -H 'X-Payment: <x402-payment-header>' \
  -d '{
    "chain": "ethereum",
    "token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
    "label_type": "smart_money",
    "pagination": {"page": 1, "per_page": 10}
  }'

Example

Request

{
  "chain": "ethereum",
  "filters": {
    "value_usd": {
      "min": 10000
    },
    "include_smart_money_labels": [
      "Fund",
      "Smart Trader"
    ]
  },
  "order_by": [
    {
      "field": "value_usd",
      "direction": "DESC"
    }
  ],
  "label_type": "smart_money",
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"
}

Response

{
  "data": [
    {
      "address": "0x1234567890123456789012345678901234567890",
      "value_usd": 150000,
      "token_amount": 50000,
      "total_inflow": 52000,
      "address_label": "Smart Trader Fund A",
      "total_outflow": 2000,
      "balance_change_7d": 5000,
      "balance_change_24h": 1500,
      "balance_change_30d": 15000,
      "ownership_percentage": 0.33
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": false
  }
}

Endpoint

URLhttps://api.nansen.ai/api/v1/tgm/holders
Transporthttp
Protocolx402
Pay to0x93053f1e7A5eFEDa532Fe69CbbE43cBEc3A0F13f
CurrencyUSD COIN

Quality

0.92/ 1.00

Full OpenAPI 3.1 schema with detailed request/response models, clear x402 payment info ($0.05/call), live 402 challenge confirmed, comprehensive filter and sort documentation. Minor gap: no crawled docs page (returns 404), but the OpenAPI spec is thorough.

Warnings

  • —No browsable documentation page found at api.nansen.ai/docs — rely on the OpenAPI spec
  • —Native tokens with label_type 'all_holders' have limited filter/sort options per the API description

Citations

Provenance

Indexed fromx402_bazaar
Enriched2026-04-22 01:40:30Z · anthropic/claude-opus-4.6 · v2
First seen2026-04-21
Last seen2026-04-22

Agent access

JSONhttps://clawmart.sh/api/listings/8cPJYy