> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Track Token Holders Across Ethereum, Solana, BNB, Base & More

> Retrieve the top holders of any token, including holder tags, balances, supply share, and USD value, using the Mobula API.

The [**Get Token Holders**](https://docs.mobula.io/rest-api-reference/endpoint/token-holder-positions) 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**.

***

<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
  <iframe src="https://www.youtube.com/embed/dTVVXZrui6M" title="YouTube video player" style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0 }} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen />
</div>

***

## 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](https://admin.mobula.io/)

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**](https://docs.mobula.io/rest-api-reference/endpoint/wallet-activity) or [**wallet/positions**](https://docs.mobula.io/rest-api-reference/endpoint/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)

| Parameter    | Description                                                                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`      | Token contract address                                                                                                                                        |
| `blockchain` | Chain identifier (example: `1` for [Ethereum](https://docs.mobula.io/blockchains/ethereum), `solana` for [Solana](https://docs.mobula.io/blockchains/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](https://mobula-demo-endpoint-production.up.railway.app/)

[Token Holders Demo UI](https://mobula-demo-endpoint-production.up.railway.app/token-holders)

[Docs](https://docs.mobula.io/rest-api-reference/endpoint/token-holder-positions)

***

## Summary

The [Get Token Holders](https://docs.mobula.io/rest-api-reference/endpoint/token-holder-positions) 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](https://admin.mobula.io/)