Token - Holder

curl --request GET \
  --url https://public-api.birdeye.so/defi/v3/token/holder \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://public-api.birdeye.so/defi/v3/token/holder', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "holder": 120450,
    "top10HoldPercent": 18.42,
    "items": [
      {
        "amount": "4995300410087424",
        "decimals": 9,
        "mint": "So11111111111111111111111111111111111111112",
        "owner": "AVzP2GeRmqGphJsMxWoqjpUifPpCret7LqWhD8NWQK49",
        "token_account": "BUvduFTd2sWFagCunBPLupG8fBTJqweLw9DuhruNFSCm",
        "ui_amount": 4995300.410087424,
        "is_scaled_ui_token": false,
        "multiplier": null
      }
    ]
  }
}

GET

defi

token

holder

Token - Holder

curl --request GET \
  --url https://public-api.birdeye.so/defi/v3/token/holder \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://public-api.birdeye.so/defi/v3/token/holder', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "holder": 120450,
    "top10HoldPercent": 18.42,
    "items": [
      {
        "amount": "4995300410087424",
        "decimals": 9,
        "mint": "So11111111111111111111111111111111111111112",
        "owner": "AVzP2GeRmqGphJsMxWoqjpUifPpCret7LqWhD8NWQK49",
        "token_account": "BUvduFTd2sWFagCunBPLupG8fBTJqweLw9DuhruNFSCm",
        "ui_amount": 4995300.410087424,
        "is_scaled_ui_token": false,
        "multiplier": null
      }
    ]
  }
}

Usage Note
Accessibility
Chain Supported

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 30 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.

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

address

string

required

The address of the token contract.

offset

integer

default:0

Pagination start position. offset + limit <= 10000

Required range: 0 <= x <= 10000

limit

integer

default:100

Number of items per page.

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

Response containing a paginated list of token holders for a Solana token.

success

boolean

required

Indicates whether the request was successful.

data

object

required

Paginated token holder result.

Show child attributes