Skip to main content
The Get Token Holders endpoint returns a ranked list of token holders for a specific asset, including enriched metadata like wallet tags (dev, LP, holder), token amounts, total supply share, and estimated USD value. It is ideal for developers building holder dashboards, token analytics tools, risk monitoring, and on-chain research apps.

​
What this endpoint does

With this API, you can:
  • Fetch the top token holders for a specific asset
  • Retrieve holder balances in raw units and formatted token amounts
  • Get each holder’s share of total supply (percentage)
  • Estimate holder balance value in USD
  • Receive enriched holder tags (dev, LP pairs, holder, etc.)
  • Paginate through holders with limit and offset
  • Optionally include historical holders with zero balance
Unlike a basic “holders list,” this endpoint returns enriched holder metadata that’s ready to display in a UI.

​
What you’ll need

  • Basic knowledge of REST APIs
  • A token contract address (recommended) or token name
  • A blockchain identifier (required when using contract address)
  • A Mobula API key
Note: All Mobula endpoints require an API key.
Get a free API key: Here Optional:
  • DexScreener or a block explorer to find token contract addresses quickly

​
When to use Get Token Holders

Use this endpoint when you want to:
  • Build a “Top Holders” table for a token page
  • Track whales and concentration risk (top supply holders)
  • Identify dev wallets or LP-related addresses via tags
  • Monitor token distribution changes with pagination and offsets
  • Include historical holders who sold out (includeZeroBalance=true)
If you need wallet-level analytics, use wallet endpoints like wallet/activity or wallet/positions.

​
Walkthrough — Get Token Holders for a Token

​
1. Prepare your query

The market/token/holders endpoint supports two common query modes. Recommended: Contract address mode (most accurate)
ParameterDescription
assetToken contract address
blockchainChain identifier (example: 1 for Ethereum, solana for Solana)
Optional parameters you can use to control output:
  • limit (max 100): number of holders returned (default 20)
  • offset: pagination offset (default 0)
  • includeZeroBalance: include historical holders who now have 0 balance (default false)
Alternative: Name mode You can also set asset=Bitcoin or asset=Ethereum, but contract address + blockchain is the safest for exact matches. Note: backfill exists as a feature, but you do not need it for the typical “top holders” use case.

​
2. Find a token contract address

To get a valid token address quickly:
  • Open DexScreener (or a block explorer)
  • Search for the token you want to analyze
  • On the token page, copy the contract address
  • Confirm the chain (Solana, Ethereum, Base, etc.) so you can fill the blockchain parameter correctly

​
3. Fill the API form

Back in the endpoint “Try it” form:
  • Paste the contract address into the asset field
  • Fill in blockchain for the chain the token is deployed on
  • Set limit and offset if you want pagination
  • Click Send

​
Reviewing the token holders response

The response returns a ranked list of holders plus a total count. What you typically get per holder:
  • address: the holder wallet address
  • amountRaw: raw token balance (before decimals)
  • amount: formatted token balance
  • chainId: chain identifier (example: ethereum:1, solana:solana)
  • totalSupplyShare: % of total supply held by the wallet
  • amountUSD: estimated USD value of the holdings
  • tag: enriched label (dev, LP pair label, holder, etc.)
This makes it easy to build a top holders table with supply concentration and wallet tagging.

​
Try It Live with Mobula Token Holders Demo (UI)

You can also test this endpoint using our demo UI: Demo UI Homepage Token Holders Demo UI Docs

​
Summary

The Get Token Holders endpoint helps you retrieve and display token distribution data, including:
  • Top holders ranked by balance
  • Token balance amounts (raw and formatted)
  • USD value estimates
  • Total supply share per holder
  • Enriched holder tags
  • Pagination with limit and offset
  • Optional inclusion of zero-balance historical holders
If you’re building token pages, holder dashboards, or monitoring tools, this endpoint is a strong foundation for token distribution analytics.

​
Try Mobula for Free

Try our free API today and start building in minutes.
Get your free API key: Here