API Endpoints

Token - Holder

get
https://public-api.birdeye.so/defi/v3/token/holder

Retrieve top holders of a Solana token. By default, results are returned per token account. Set mode=wallet to group token accounts by owner wallet and include wallet-level holder stats.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Top holders for one token, with token-account mode and wallet mode.

  • mode=token_account returns the legacy view: one row per token account.
  • mode=wallet groups token accounts by owner wallet and returns wallet-level holder stats.
  • get_holder_infos=true is only supported when mode=wallet. It adds netWorth, solBalance, and funding to each holder row and may make the response slightly slower.
  • Holder rows always include raw balance (amount), token decimals, mint address, owner wallet, and ui_amount. token_account is returned for token-account rows; wallet mode adds wallet-level stats such as amountUsd, holdAvgPrice, avgBuyPrice, avgSellPrice, firstTradeUnixTime, and lastTradeUnixTime.
  • Top-level holder and top10HoldPercent follow the selected mode: token-account holder stats in token_account mode, wallet-level holder stats in wallet mode.
  • ui_amount_mode=scaled applies Solana Token-2022 scaled UI amount when the token supports scaled UI amount extension.
  • Use offset and limit to page through holders.

Reading the numbers. amount is the raw balance before decimals in token-account mode, or the grouped wallet holding amount in wallet mode. ui_amount is the balance after applying decimals or Token-2022 scaled UI amount when requested and supported. amountUsd is wallet holding value in USD. holdAvgPrice describes the current wallet position cost; avgBuyPrice and avgSellPrice summarize historical trade prices.

Compute Unit ⚙️
  • This endpoint consumes 35 CU per request.
Use Cases 💡
  • Find the largest token holders and inspect the wallet owners behind major balances.
  • Build top-holder tables for token profile pages, holder dashboards, and risk review workflows.
  • Detect concentration risk by combining holder balances with total supply and holder-distribution data.
  • Switch to wallet mode when you need true wallet-level concentration instead of token-account fragmentation.
  • Identify wallets or token accounts worth deeper investigation before listing, trading, or monitoring a token.
How to Use 🛠️
  • Provide a Solana token_address.
  • Choose mode=token_account for raw account-level ownership, or mode=wallet to collapse token accounts by owner wallet.
  • Set get_holder_infos=true only with mode=wallet when you need holder net worth, SOL balance, and funding details.
  • Use limit to control page size and offset to move through the holder list.
  • Set ui_amount_mode=raw for raw decimal-adjusted amounts, or ui_amount_mode=scaled for Solana Token-2022 scaled UI amounts when supported.
  • Use the returned owner for wallet-level analysis and token_account for account-level investigation.
Best Practices ✅
  • Start with mode=wallet when the goal is concentration analysis, whale tracking, or wallet research.
  • Use mode=token_account when you need the exact token-account distribution, custodial splits, or account-level investigation.
  • Start with the first page to inspect top holders, then page further only when you need long-tail ownership.
  • Combine this endpoint with holder-distribution to quantify how concentrated the top holders are.
  • Use owner wallet addresses with wallet intelligence APIs to understand broader portfolio behavior.
  • Enable get_holder_infos only when the extra wallet context is needed.
  • Keep ui_amount_mode consistent across holder, overview, and market-data calls when analyzing Token-2022 scaled UI amount tokens.
Limitations ⚠️
  • Solana only.
  • Pagination supports offset up to 10,000 and limit up to 100.
  • This endpoint returns holder balances, not trade history, PnL, or wallet labels.
  • get_holder_infos is only available when mode=wallet.
  • ui_amount_mode=scaled only changes amounts for tokens that support Solana Token-2022 scaled UI amount extension.

Query Params
string
required

The address of the token contract.

integer
0 to 10000
Defaults to 0

Pagination start position. offset + limit <= 10000

integer
1 to 100
Defaults to 100

Number of items per page.

string
enum
Defaults to token_account

Solana only. token_account returns one item per token account and keeps the legacy response. wallet groups token accounts by owner wallet and returns wallet-level holder stats.

Allowed:
boolean
Defaults to false

Solana only. Only available when mode=wallet. When true, the response includes netWorth, solBalance, and funding for each holder. This may make the response slightly slower than when disabled.

string
enum
Defaults to scaled

Indicate whether to use the scaled amount for scaled ui amount tokens. Only support solana

Allowed:
Headers
string
enum
Defaults to solana

Solana network only.

Allowed:
Responses

Updated about 11 hours ago

Did this page help you?
Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 11 hours ago

Did this page help you?