[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-77719":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":43,"readmeContent":44,"aiSummary":45,"trendingCount":16,"starSnapshotCount":16,"syncStatus":46,"lastSyncTime":47,"discoverSource":48},77719,"solana-top-token-holders-and-whales-api","vybenetwork\u002Fsolana-top-token-holders-and-whales-api","vybenetwork","Solana Top Token Holders & Whales API: Demonstrates Vybe Solana Top Holders API with token details, trades, labeled programs, and top traders for SPL and Token-2022 holder visualization and concentration. Reference implementation or starter kit for holder dashboards, distribution explorers, whale monitoring, and compliance or forensics workflows.","https:\u002F\u002Fdocs.vybenetwork.com",null,"TypeScript",217,84,108,1,0,79,50.69,false,"main",true,[23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"api","birdeye","gmgn","holder","holders","holders-api","kolscan","nansen","pumpfun","pumpswap","raydium","solana","solana-api","solana-endpoint","solscan","spl","token-2022","traders","trades","wallet-balances","2026-06-12 04:01:22","# Solana Top Token Holders & Whales API\n\nThis repository demonstrates how to use the Vybe Solana **Top Holders** API to fetch, visualize, and export *who owns what* for any SPL or Token-2022 token. It includes a production-ready Node.js backend and a modern, framework-free frontend that show how to:\n\n- Fetch **token metadata** (symbol, name, supply, market cap, update time)\n- Fetch **top holders** with pagination and sorting\n- Compute **cohort concentration** metrics and distributions\n- Group **labeled entities** (Vybe names\u002Flabels) into rollups\n- Pull **recent trades** and **top traders** as optional context\n\nTry the live demo: https:\u002F\u002Fsolana-top-token-holders-and-whales-api.vybenetwork.com\n\nUse this project as a reference implementation or starter kit for building Solana holder dashboards, token distribution explorers, whale-monitoring tools, and compliance\u002Fforensics workflows powered by Vybe’s high-performance Solana data APIs.\n\n![Solana Top Token Holders & Whales API Repo](screenshots\u002Fsolana-top-token-holders-and-whales-api-vybe.png)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"screenshots\u002Fapi-for-solana-top-token-holders-vybe.png\" alt=\"Fetch top holders and supply charts\" width=\"440\" style=\"min-width:440px;max-width:440px;margin-right:10px;\" \u002F>\n  \u003Cimg src=\"screenshots\u002Fapi-for-solana-top-token-holders-and-whales.png\" alt=\"Top holders API dashboard sections\" width=\"320\" style=\"min-width:320px;max-width:320px;\" \u002F>\n\u003C\u002Fp>\n\n---\n\n**[Try the LIVE demo →](https:\u002F\u002Fsolana-top-token-holders-and-whales-api.vybenetwork.com)**\n\n**[Get your free Vybe API key →](https:\u002F\u002Fvybenetwork.com\u002Fpricing)**  \n\n**[Vybe Top Holders docs →](https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_top_holders_v4)**\n\n---\n\n## Prerequisites\n\n- **Node.js** ≥ 20 (LTS recommended)\n- **npm** ≥ 10 (or equivalent)\n\n## Quick Start\n\nGet from clone to running app in a few commands:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fvybenetwork\u002Fsolana-top-token-holders-and-whales-api.git\ncd solana-top-token-holders-and-whales-api\nnpm install\ncp .env.example .env\n# Edit .env and set VYBE_API_KEY=your_api_key_here\nnpm start\n```\n\nThen open **http:\u002F\u002Flocalhost:3000**, enter a token mint, and click **Load Holders & Whales**.\n\n## Environment Variables\n\n| Variable | Required | Description | Example |\n|---|---:|---|---|\n| `VYBE_API_KEY` | Yes | Vybe API key used for all Vybe requests | `your_api_key_here` |\n| `SOLANA_RPC_URL` | No | Solana RPC used for Metaplex symbol fallback (defaults to mainnet-beta) | `https:\u002F\u002Fapi.mainnet-beta.solana.com` |\n| `PORT` | No | HTTP server port | `3000` |\n| `TUNNEL` | No | Set to `1` to run behind a Cloudflare Tunnel (requires `cloudflared`) | `1` |\n| `TRADES_LOG` | No | Set to `1` to log `\u002Fapi\u002Ftrades` request URLs to `trades-requests.log` | `1` |\n\nGet your API key at `https:\u002F\u002Fvybenetwork.com\u002Fpricing`.\n\n---\n\n## What This Repo Provides\n\n- **Vybe API proxy server**\n  - Express server that proxies Vybe endpoints (keeps API key server-side) and serves the frontend from `public\u002F`.\n  - Endpoints exposed by this app:\n    - `GET \u002Fapi\u002Ftokens\u002F:mint` (token metadata)\n    - `GET \u002Fapi\u002Ftokens\u002F:mint\u002Ftop-holders` (top holders)\n    - `GET \u002Fapi\u002Ftrades` (recent trades for the mint)\n    - `GET \u002Fapi\u002Fprograms\u002Flabeled-program-account?programAddress=...` (single program label lookup; cached)\n    - `POST \u002Fapi\u002Fprograms\u002Flabeled-program-accounts` (batch program label lookup; cached)\n    - `GET \u002Fapi\u002Fwallets\u002Ftop-traders` (optional context)\n    - `GET \u002Fapi\u002Ftoken-symbol\u002F:mint` and `POST \u002Fapi\u002Ftoken-symbols` (symbol fallback; cached)\n- **Top holders web UI**\n  - Single-page GUI (no frameworks) built from `src\u002Ffrontend\u002Fapp.ts` into `public\u002Fapp.js`.\n  - Lets you inspect holder distribution, concentration metrics, labeled entity rollups, and the top-holders table for any mint.\n- **On-disk caches**\n  - JSON caches stored in `data\u002F`:\n    - `data\u002Fsymbol-cache.json`\n    - `data\u002Fprogram-label-cache.json`\n\nAll of this uses Vybe’s production data across SPL + Token-2022 mints.\n\n---\n\n### Solana API docs for these endpoints\n\n- **Top holders (`GET \u002Fv4\u002Ftokens\u002F{mintAddress}\u002Ftop-holders`)**:\n  - [https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_top_holders_v4](https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_top_holders_v4)\n- **Token details (`GET \u002Fv4\u002Ftokens\u002F{mintAddress}`)**:\n  - [https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_token_details_v4](https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_token_details_v4)\n- **Historical trades (`GET \u002Fv4\u002Ftrades`)**:\n  - [https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_trade_data_program_v4](https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_trade_data_program_v4)\n- **Labeled programs (`GET \u002Fv4\u002Fprograms\u002Flabeled-program-accounts`)**:\n  - [https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_known_program_accounts_v4](https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_known_program_accounts_v4)\n- **Top traders (`GET \u002Fv4\u002Fwallets\u002Ftop-traders`)**:\n  - [https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_top_traders_v4](https:\u002F\u002Fdocs.vybenetwork.com\u002Freference\u002Fget_top_traders_v4)\n\n---\n\n## Why Top Holders \u002F Whale Data Matters\n\nTop-holder and whale distribution data is critical for:\n\n- **Risk & concentration**: identify tokens dominated by a small set of wallets.\n- **Token launches & monitoring**: track the emergence (and exit) of whales over time.\n- **Entity intelligence**: group labeled wallets (CEXs, market makers, team wallets) to understand true ownership.\n- **Compliance & forensics**: quickly highlight clusters for deeper investigation.\n\nThis repo shows how to build a **practical holder explorer** on top of Vybe’s `top-holders` endpoint, with supporting metadata and labeling.\n\n---\n\n## Frontend Overview (Top Holders Dashboard)\n\nThe UI is implemented in `src\u002Ffrontend\u002Fapp.ts` and compiled to `public\u002Fapp.js` via `npm start` (which runs `npm run build:frontend` first).\n\n### Sections\n\n- **Remote filters**\n  - Mint address, sort direction, limit\u002Fpage controls.\n  - Fetches a top-holders page from `GET \u002Fapi\u002Ftokens\u002F:mint\u002Ftop-holders`.\n- **Token metadata header**\n  - Symbol, name, last updated, price\u002Fmarket cap\u002Fsupply where available (from `GET \u002Fapi\u002Ftokens\u002F:mint`).\n  - Falls back to Metaplex-based symbol lookup via `\u002Fapi\u002Ftoken-symbol\u002F:mint` when needed.\n- **Supply & holder charts**\n  - **Top wallets vs circulating supply** donut and tier cards.\n  - **Supply concentration** (fetched cohort) metrics + Gini-style score.\n  - **Cohort distribution & labeled groups**: per-holder % histogram, USD histogram, and top labeled groups (first-token grouping).\n  - **Labeled vs unlabeled supply**: donut and tier cards within the fetched cohort.\n- **Top holders table**\n  - One row per holder: rank, owner name\u002Faddress, balance, USD value estimate, % of supply.\n\n### Value formatting rules (holder dashboards)\n\n- **Large values**: compact \\(K\u002FM\u002FB\\) formatting; when the coefficient exceeds 999, decimals are dropped and thousands separators are shown (e.g. `37,503B`).\n- **Commas**: integer displays use `en-US` thousands separators.\n\n---\n\n## Server Proxy Routes\n\nThe Express server in `src\u002Fserver.ts` exposes:\n\n- **`GET \u002Fapi\u002Ftokens\u002F:mint`**\n  - Proxies Vybe token details for the header.\n- **`GET \u002Fapi\u002Ftokens\u002F:mint\u002Ftop-holders`**\n  - Proxies Vybe top holders with limit\u002Fpage and sort.\n- **`GET \u002Fapi\u002Ftrades`**\n  - Proxies Vybe trades (mintAddress required; limit\u002Fpage\u002FtimeStart\u002FtimeEnd supported).\n- **`GET \u002Fapi\u002Fprograms\u002Flabeled-program-account`**\n  - Single program label lookup (cached).\n- **`POST \u002Fapi\u002Fprograms\u002Flabeled-program-accounts`**\n  - Batch program label lookup (cached).\n- **`GET \u002Fapi\u002Fwallets\u002Ftop-traders`**\n  - Optional context: top traders for a mint at a resolution (default `30d`).\n- **`GET \u002Fapi\u002Ftoken-symbol\u002F:mint`** and **`POST \u002Fapi\u002Ftoken-symbols`**\n  - Symbol resolution and batch symbol cache warmup.\n\nAll Vybe requests use a shared client (`src\u002Fapi\u002Findex.ts`) with timeouts, retries, and consistent error formatting (`toHumanReadableError`).\n\n---\n\n## How to Run\n\n### 1. Clone the repository\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fvybenetwork\u002Fsolana-top-token-holders-and-whales-api.git\ncd solana-top-token-holders-and-whales-api\n```\n\n### 2. Install dependencies\n\n```bash\nnpm install\n```\n\n### 3. Set your API key\n\n```bash\ncp .env.example .env\n# Add your VYBE_API_KEY to .env\n```\n\n### 4. Run the server + web app\n\n```bash\nnpm start\n```\n\nThen open **http:\u002F\u002Flocalhost:3000** and load a token mint.\n\n### 5. (Optional) Run with Cloudflare Tunnel\n\nTo expose the app on a public URL (e.g. for sharing or testing from another device), you can enable a tunnel (requires `cloudflared` installed):\n\n```bash\nTUNNEL=1 npm start\n```\n\nThe console prints a Cloudflare Tunnel URL when available.\n\n---\n\n## Project Structure\n\n```text\nsolana-top-token-holders-and-whales-api\u002F\n├── .env.example\n├── package.json\n├── tsconfig.json\n├── tsconfig.frontend.json\n├── README.md\n├── screenshots\u002F                 # Screenshots referenced in this README (you update these)\n├── public\u002F                      # Web GUI (HTML, CSS, built JS)\n│   ├── index.html\n│   ├── app.css\n│   └── app.js                   # Generated by `npm run build:frontend` from src\u002Ffrontend\u002Fapp.ts\n├── dist\u002F                        # Backend build output (`npm run build`)\n└── src\u002F\n    ├── server.ts                # Express server; proxies Vybe API and serves public\u002F\n    ├── config.ts                # Env loading, API base URL, timeouts, PUBLIC_DIR\n    ├── cache.ts                 # On-disk caches in data\u002F\n    ├── types\u002F\n    │   └── api.ts               # Interfaces matching Vybe API response shapes\n    ├── api\u002F\n    │   ├── index.ts             # createClient(apiKey) — wires all API methods\n    │   ├── client.ts            # Axios wrapper, retries, human-readable errors\n    │   ├── tokens.ts            # GET \u002Fv4\u002Ftokens\u002F{mintAddress}\n    │   ├── holders.ts           # GET \u002Fv4\u002Ftokens\u002F{mintAddress}\u002Ftop-holders\n    │   ├── trades.ts            # GET \u002Fv4\u002Ftrades + programs + top traders\n    │   └── token-symbol.ts      # Metaplex + hardcoded WSOL\u002FUSDC symbol fallback\n    └── frontend\u002F\n        └── app.ts               # Holders dashboard UI → builds to public\u002Fapp.js\n```\n\n---\n\n## Direct API Usage Example\n\nIf you want to bypass the UI and fetch top holders using Vybe directly:\n\n```typescript\nimport axios from 'axios';\n\nconst API = 'https:\u002F\u002Fapi.vybenetwork.xyz';\nconst headers = { 'X-API-KEY': process.env.VYBE_API_KEY!, Accept: 'application\u002Fjson' };\n\ntype Holder = {\n  rank?: number;\n  ownerAddress?: string;\n  ownerName?: string;\n  balance?: string | number;\n  valueUsd?: number;\n  percentageOfSupplyHeld?: number;\n};\n\nasync function fetchTopHolders(mintAddress: string, limit = 1000, page = 0) {\n  const { data } = await axios.get\u003C{ data: Holder[] }>(`${API}\u002Fv4\u002Ftokens\u002F${mintAddress}\u002Ftop-holders`, {\n    params: { limit, page, sortByDesc: 'percentageOfSupplyHeld' },\n    headers,\n  });\n  return data.data || [];\n}\n\nconst mint = 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263';\nfetchTopHolders(mint, 1000, 0).then((holders) => {\n  console.log('top holders:', holders.length);\n  console.log('first row:', holders[0]);\n});\n```\n\n---\n\n## Troubleshooting\n\n| Issue | What to do |\n|---|---|\n| **403 Forbidden** | Verify `VYBE_API_KEY` in `.env` is correct and has access to the needed endpoints. If the key works locally but not on a server, it may be IP-restricted — contact Vybe to allow your server IP. |\n| **No symbol \u002F weird symbol** | Set `SOLANA_RPC_URL` to a reliable mainnet RPC; the symbol fallback uses Metaplex metadata and retries a few times. |\n| **Slow responses \u002F timeouts** | The app uses a 60s timeout for Vybe requests and retries. If the API is under load, you may see timeouts; retry later. |\n\n---\n\n## Support\n\n- **Telegram:** [Vybe community](https:\u002F\u002Ft.me\u002Fvybenetwork)\n- **Support ticket:** [Submit a ticket](https:\u002F\u002Fvybenetwork.com)\n\n","该项目提供了一个Solana顶级代币持有者和巨鲸的API，用于获取、可视化并导出任何SPL或Token-2022代币的持有情况。其核心功能包括获取代币元数据（如符号、名称、供应量等）、分页和排序展示顶级持有者、计算持有者集中度指标以及显示最近交易和顶级交易者信息。技术上采用TypeScript编写，并提供了生产就绪的Node.js后端及现代化无框架前端。适合于构建Solana持有人仪表板、代币分布探索器、巨鲸监控工具以及合规性或法证工作流等场景。",2,"2026-06-11 03:55:58","CREATED_QUERY"]