Token Holders (Top 1000)

Why Holder Data Matters

Holder analysis is critical for:

Due diligence: Is the token concentrated in a few wallets?
Whale tracking: Are large holders accumulating or distributing?
Market intelligence: When CEXs accumulate, big moves often follow
Community health: How distributed is ownership?

Vybe's holder data goes beyond raw addresses. We label known entities (CEXs, KOLs, protocols) so you can instantly see who the major holders are—not just anonymous wallet addresses.

Endpoint

GET /tokens/{mintAddress}/holders

Parameters

Parameter	Type	Description
`mintAddress`	string	Token mint public key (required)
`sortByAsc`	string	Sort ascending
`sortByDesc`	string	Sort descending (default: `rank`)
`limit`	number	Results per page (max 1000)
`page`	number	Page number (0-indexed)

Sort Options

Option	Description
`rank`	By holder position (1 = largest)
`ownerName`	Alphabetically by entity name
`ownerAddress`	By wallet address
`valueUsd`	By USD value held
`balance`	By token amount
`percentageOfSupplyHeld`	By ownership percentage

Example Request

curl "https://api.vybenetwork.com/tokens/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "mintAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "symbol": "BONK",
  "totalHolders": 892345,
  "data": [
    {
      "rank": 1,
      "ownerAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "ownerName": "Binance Hot Wallet 1",
      "ownerLabel": "CEX",
      "balance": "12345678901234.56",
      "valueUsd": "1234567.89",
      "percentageOfSupplyHeld": "12.34"
    },
    {
      "rank": 2,
      "ownerAddress": "7Tar8QZTrRPwoGY5Ke9Vfwf6CmpBfekrNofERxgReza",
      "ownerName": null,
      "ownerLabel": null,
      "balance": "9876543210987.65",
      "valueUsd": "987654.32",
      "percentageOfSupplyHeld": "9.87"
    }
  ]
}

Response Fields Explained

Field	Description
`totalHolders`	Total number of unique holders
`rank`	Holder position (1 = largest holder)
`ownerAddress`	Wallet public key
`ownerName`	Entity name if wallet is labeled
`ownerLabel`	Category: CEX, KOL, DEFI, VC, etc.
`balance`	Token amount held (human-readable)
`valueUsd`	Current USD value of holdings
`percentageOfSupplyHeld`	Percentage of circulating supply

Entity Labels

When a holder is a known entity, we provide their label:

Label	Description
`CEX`	Centralized exchange (Binance, Coinbase, etc.)
`KOL`	Key opinion leader / influencer
`DEFI`	DeFi protocol wallet
`VC`	Venture capital firm
`MM`	Market maker
`TREASURY`	Project treasury

Unknown wallets have null for ownerName and ownerLabel.

Common Use Cases

Use Case	Implementation
Holder Leaderboard	Display top holders on token page
Concentration Analysis	Check if whales dominate supply
Distribution Audit	Verify fair token distribution
Whale Alerts	Monitor changes in top holders
CEX Tracking	Watch exchange accumulation
Insider Detection	Identify connected wallets

Concentration Analysis Example

Analyze token distribution health:

async function analyzeTokenConcentration(mintAddress) {
  const response = await fetch(
    `https://api.vybenetwork.com/tokens/${mintAddress}/holders?limit=100`,
    { headers: { "X-API-Key": API_KEY } }
  );
  const { data, totalHolders } = await response.json();
  
  // Top 10 concentration
  const top10Percent = data.slice(0, 10)
    .reduce((sum, h) => sum + parseFloat(h.percentageOfSupplyHeld), 0);
  
  // Top 50 concentration
  const top50Percent = data.slice(0, 50)
    .reduce((sum, h) => sum + parseFloat(h.percentageOfSupplyHeld), 0);
  
  // CEX holdings
  const cexHoldings = data
    .filter(h => h.ownerLabel === "CEX")
    .reduce((sum, h) => sum + parseFloat(h.percentageOfSupplyHeld), 0);
  
  // Labeled whales vs unknown
  const labeledCount = data.filter(h => h.ownerName).length;
  
  // Health score (lower concentration = better)
  let health = "Healthy";
  if (top10Percent > 80) health = "Critical - Extreme concentration";
  else if (top10Percent > 60) health = "Warning - High concentration";
  else if (top10Percent > 40) health = "Moderate concentration";
  
  return {
    totalHolders: totalHolders.toLocaleString(),
    top10Concentration: `${top10Percent.toFixed(2)}%`,
    top50Concentration: `${top50Percent.toFixed(2)}%`,
    cexHoldings: `${cexHoldings.toFixed(2)}%`,
    labeledWalesInTop100: `${labeledCount}/100`,
    healthScore: health
  };
}

Whale Movement Tracker

Compare snapshots to detect accumulation/distribution:

async function trackWhaleMovements(mintAddress, previousSnapshot) {
  const response = await fetch(
    `https://api.vybenetwork.com/tokens/${mintAddress}/holders?limit=50`,
    { headers: { "X-API-Key": API_KEY } }
  );
  const { data: current } = await response.json();
  
  const movements = current.map(holder => {
    const previous = previousSnapshot?.find(
      h => h.ownerAddress === holder.ownerAddress
    );
    const prevBalance = parseFloat(previous?.balance || 0);
    const currBalance = parseFloat(holder.balance);
    const change = currBalance - prevBalance;
    const changePercent = prevBalance > 0 
      ? ((change / prevBalance) * 100).toFixed(2) 
      : "New";
    
    return {
      rank: holder.rank,
      address: holder.ownerAddress,
      name: holder.ownerName || "Unknown",
      label: holder.ownerLabel,
      balance: currBalance,
      change,
      changePercent: changePercent + "%",
      action: change > 0 ? "ACCUMULATING" : change < 0 ? "DISTRIBUTING" : "HOLDING"
    };
  }).filter(h => h.change !== 0);
  
  return {
    accumulating: movements.filter(m => m.change > 0),
    distributing: movements.filter(m => m.change < 0)
  };
}

Related Endpoints

Holder History - Track holder count over time
Token Details - Token metadata and metrics
Labeled Wallets - Full entity database