Skip to main content
GET
Token - Holder Distribution

Two distribution modes. Pick one mode and only use filters for that mode.

  • mode=top — returns the top holders by supply share. Use top_n to control how many top holders to inspect.
  • mode=percent — returns holders inside a supply-share range. Use min_percent and max_percent to define the range.
  • address_type=wallet returns holder wallets. address_type=token_account returns token-account level ownership.
  • include_list=true returns the holder list. Set include_list=false when you only need the summary.

Reading the numbers. summary.wallet_count is the number of holders in the selected range. summary.total_holding is the total token amount held by that segment, and summary.percent_of_supply is that segment’s share of total supply.

  • This endpoint consumes 30 CU per request.
  • Map the ownership shape of a token before trusting the market: see whether supply is spread across many wallets or concentrated in a few dominant hands.
  • Build concentration-risk dashboards that flag tokens where the top holders control a dangerous share of supply.
  • Segment holders by supply percentage to identify whales, mid-size holders, and long-tail retail distribution.
  • Compare wallet-level and token-account-level views to understand whether apparent distribution is real or fragmented across accounts.
  • Feed token safety scores, listing reviews, and pre-trade checks with holder concentration signals.
  • Provide a Solana token_address.
  • Use mode=top&top_n=10 for the largest holders, or mode=percent&min_percent=1&max_percent=5 for a supply-share bucket.
  • Set address_type=wallet for owner-level analysis, or address_type=token_account for token-account level inspection.
  • Set include_list=false for a lightweight summary, or keep it true when you need the actual holder rows.
  • Use offset and limit to page through the holder list when include_list=true.
  • Start with mode=top to identify concentration risk, then use mode=percent to inspect the middle and long-tail ownership bands.
  • Do not mix top-holder filters with percent-range filters; each mode has its own filter set.
  • Use wallet-level distribution for product and risk summaries, and token-account level distribution when investigating account fragmentation.
  • Pair distribution with holder-profile, first-buyers, and token overview data to understand who owns supply and whether ownership looks healthy.
  • Solana only.
  • mode=top cannot be combined with min_percent or max_percent.
  • mode=percent cannot be combined with top_n.
  • top_n supports up to 10,000 holders.
  • Pagination supports offset up to 10,000 and limit up to 50.

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Headers

​
x-chain
enum<string>
default:solana

Solana network only.

Available options:
solana

Query Parameters

​
token_address
string
required

Token contract address.

​
address_type
enum<string>
default:wallet

Return holder distribution by wallet or token account address.

Available options:
wallet,
token_account
​
mode
enum<string>
default:top

Holder filter mode (percent = by supply % range, top = top holders by supply %).

Available options:
percent,
top
​
top_n
integer
default:10

Number of top holders to return (used only when mode = top).

Required range: 1 <= x <= 10000
​
min_percent
number

Minimum % of total supply a holder must have (used only when mode = percent).

Required range: 0 <= x <= 100
​
max_percent
number

Maximum % of total supply a holder can have (used only when mode = percent).

Required range: 0 <= x <= 100
​
include_list
boolean
default:true

Return holder list (true / false).

​
offset
integer
default:0

Pagination start position. offset + limit <= 10000

Required range: 0 <= x <= 10000
​
limit
integer
default:50

Number of items per page.

Required range: 1 <= x <= 50

Response

JSON object containing token holder distribution details

Response containing holder-distribution summary data and optional holder rows.

​
success
boolean
required

Whether the request succeeded.

​
data
object
required

Holder-distribution payload for the requested token and mode.