---
title: "Get Token Holder Positions"
method: GET
path: "/api/2/token/holder-positions"
tags: ["V2 - Token"]
---

# Get Token Holder Positions

`GET /api/2/token/holder-positions`

Returns the top holders for a token ranked by balance. Each entry includes wallet address, token balance, percentage of supply held, USD value, wallet labels (e.g. INSIDER, SNIPER, BUNDLER, CEX), and entity name if identified. Use for whale watching, concentration analysis, and supply distribution audits.

## Query parameters

- `chainId` string — Blockchain chain ID (e.g., "evm:56", "solana:solana")
- `address` string — Token contract address
- `label` 'sniper' | 'insider' | 'bundler' | 'proTrader' | 'smartTrader' | 'freshTrader' | 'dev' | 'liquidityPool' | 'locker' — Filter by wallet label (e.g. sniper, bundler, insider)
- `limit` number, nullable — Maximum number of results (default: 100)
- `offset` number, nullable — Offset for pagination
- `walletAddresses` union — Comma-separated wallet addresses to filter
  - string
  - string[]
- `useSwapRecipient` union, required — Use swap recipient mode for accurate Account Abstraction tracking
  - boolean
  - string
- `includeFees` union, required — Include total fees paid (gas + platform + MEV) and deduct from PnL
  - boolean
  - string

## Response `200`

Token Holder response

- object
  - `data` object[], required
    - `chainId` string, required
    - `walletAddress` string, required
    - `tokenAddress` string, required
    - `tokenAmount` string, required
    - `tokenAmountRaw` string, required
    - `tokenAmountUSD` string, required
    - `percentageOfTotalSupply` string, required
    - `pnlUSD` string, required
    - `realizedPnlUSD` string, required
    - `unrealizedPnlUSD` string, required
    - `totalPnlUSD` string, required
    - `totalFeesPaidUSD` string
    - `buyFeesPaidUSD` string
    - `sellFeesPaidUSD` string
    - `buys` number, required
    - `sells` number, required
    - `volumeBuyToken` string, required
    - `volumeSellToken` string, required
    - `volumeBuyUSD` string, required
    - `volumeSellUSD` string, required
    - `avgBuyPriceUSD` string, required
    - `avgSellPriceUSD` string, required
    - `nativeBalance` string
    - `nativeBalanceRaw` string
    - `walletFundAt` string, nullable, required
    - `lastActivityAt` string, nullable, required
    - `firstTradeAt` string, nullable, required
    - `lastTradeAt` string, nullable, required
    - `labels` string[], nullable
    - `walletMetadata` object, nullable
      - `entityName` string, nullable, required
      - `entityLogo` string, nullable, required
      - `entityLabels` string[], required
      - `entityType` string, nullable, required
      - `entityDescription` string, nullable, required
      - `entityTwitter` string, nullable, required
      - `entityWebsite` string, nullable, required
      - `entityGithub` string, nullable, required
      - `entityDiscord` string, nullable, required
      - `entityTelegram` string, nullable, required
      - `extra` object
    - `platform` object, nullable
      - `id` string, required
      - `name` string, required
      - `logo` string, nullable, required
    - `fundingInfo` object, required
      - `from` string, nullable, required
      - `date` string, nullable, required
      - `chainId` string, nullable, required
      - `txHash` string, nullable, required
      - `amount` string, nullable, required
      - `formattedAmount` number, nullable, required
      - `currency` object, nullable, required
        - `name` string, required
        - `symbol` string, required
        - `logo` string, nullable, required
        - `decimals` number, required
        - `address` string, required
      - `fromWalletLogo` string, nullable, required
      - `fromWalletTag` string, nullable, required
      - `fromWalletMetadata` object, nullable
        - `entityName` string, nullable, required
        - `entityLogo` string, nullable, required
        - `entityLabels` string[], required
        - `entityType` string, nullable, required
        - `entityDescription` string, nullable, required
        - `entityTwitter` string, nullable, required
        - `entityWebsite` string, nullable, required
        - `entityGithub` string, nullable, required
        - `entityDiscord` string, nullable, required
        - `entityTelegram` string, nullable, required
        - `extra` object
  - `totalCount` number, required

## Other responses

- `402` — Payment Required

---

[API](https://skmtc.net/mobula/apis/mobula-api.md) · [All operations](https://skmtc.net/mobula/apis/mobula-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mobula/mobula-api/versions/32f95d9e8ff2/schema)