Skip to main content
GET
/
1
/
market
/
token
/
holders
Get market token holders
curl --request GET \
  --url https://demo-api.mobula.io/api/1/market/token/holders
{
  "data": [
    {
      "address": "<string>",
      "tag": "<string>",
      "amountRaw": "<string>",
      "amount": 123,
      "chainId": "<string>",
      "totalSupplyShare": 123,
      "amountUSD": 123
    }
  ],
  "total_count": 123
}

​
Query Details

This endpoint returns the top token holders for a given asset, along with enriched metadata. You can query by token name, symbol, or contract address + blockchain ID. Parameters
  • asset (required) — Asset name or contract address.
  • symbol (optional) — Token ticker symbol (e.g., ETH, BTC). The API will attempt to resolve the asset by symbol. Symbols may be ambiguous; prefer asset as a contract address + blockchain for exact results.
  • blockchain (required if using address) — Blockchain identifier (e.g., 1 for Ethereum, solana for Solana).
  • limit — Number of results to return (default: 20).
  • offset — Pagination offset (default: 0).
Notes
  • If a contract address is provided in asset, it takes precedence over symbol.
  • If using symbol, results may vary if multiple tokens share the same ticker.

​
Usage Examples

# Get top holders for a token by contract address
GET /api/1/market/token/holders?asset=0x...&blockchain=1

# Get top holders for a token by name
GET /api/1/market/token/holders?asset=Bitcoin&limit=50

# Get holders with pagination
GET /api/1/market/token/holders?asset=Ethereum&limit=20&offset=20

​
Query Response

The response returns a list of token holders with enriched metadata:
  • address — Wallet address of the holder
  • amountRaw — Token balance in raw units (before applying decimals)
  • amount — Token balance in formatted units
  • chainId — Blockchain identifier (e.g., ethereum:1, solana:solana)
  • totalSupplyShare — Percentage of the total token supply held by this address
  • amountUSD — USD equivalent of the token balance
  • tag — Enriched label describing the address type (e.g., dev, LP {SYMBOL0}/{SYMBOL1}, holder)

Query Parameters

​
blockchain
string
​
asset
string
​
symbol
string
​
limit
number | null
default:20
Required range: x <= 100
​
offset
number | null
default:0
​
backfill
default:false

Response

200 - application/json

Market token holders response

​
data
object[]
required
​
total_count
number
required