Skip to main content
GET
Token - Holder

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.

  • This endpoint consumes 30 CU per request.
  • 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.
  • 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.
  • 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.
  • Robinhood returns wallet-owner holdings without Solana token-account or scaled-UI enrichment.
  • 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.

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Headers

​
x-chain
enum<string>
default:solana

Solana or Robinhood. Robinhood supports balance-change, current-net-worth, V1/V2 token balance and /defi/v3/token/holder. Other wallet history and transfer endpoints have separate chain support.

Available options:
solana,
robinhood

Query Parameters

​
address
string
required

The address of the token contract.

​
token_id
string

Robinhood only: token identity for a multi-token contract. Omit for ordinary fungible tokens. Use an unsigned UInt256 decimal string, not a JavaScript number.

Maximum string length: 78
Pattern: ^[0-9]+$
​
offset
integer
default:0

Pagination start position. offset + limit <= 10000

Required range: 0 <= x <= 10000
​
limit
integer
default:10
Required range: 1 <= x <= 100
​
mode
enum<string>
default: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.

Available options:
token_account,
wallet
​
get_holder_infos
boolean
default: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.

​
ui_amount_mode
enum<string>
default:scaled

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

Available options:
raw,
scaled

Response

JSON object containing a list of token holder

Paginated token holders on Solana or Robinhood. Solana enrichment fields are not returned for Robinhood.

​
success
boolean
required

Indicates whether the request was successful.

​
data
object
required

Paginated token holder result.