Token holders

---
name: token-holders
description: Read a Solana token's holders - holder count, 24h change in holders, the share held by the top holders, dev mints, and whether mint and freeze authority are disabled. Optionally lists the 20 largest holder accounts when SOLANA_RPC_URL is set. Use when the user asks who holds a token, how many holders it has, or how concentrated or risky its supply is.
---

# Token holders

Free and read-only. Works out of the box on Jupiter's public token data. No key needed.

## Run

```bash
node scripts/holders.mjs <mint>
node scripts/holders.mjs JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN
```

Optional: set `SOLANA_RPC_URL` to your own Solana RPC (any provider's free tier) to also get
the 20 largest holder accounts with their owners. The public Solana RPC blocks this call, so
without your own RPC that part is skipped and `largest` is `null`.

## Output

JSON on stdout: `{ mint, symbol, name, holderCount, holderChange24hPct, topHoldersPct,
devMints, mintAuthorityDisabled, freezeAuthorityDisabled, organicScore, isVerified,
largest: null | [ { rank, tokenAccount, owner, amount, pctOfSupply } ] }`.

## Notes for the agent

- `topHoldersPct` is Jupiter's share of supply held by the top holders. High values (over
  50%) mean a few wallets can move the price; say so plainly.
- Mint authority still enabled means more tokens can be created. Freeze authority enabled
  means holder accounts can be frozen.
- Some large holders are pools, exchanges or lockers, not people. Don't call them whales
  without checking.

{
  "slug": "token-holders",
  "name": "Token holders",
  "spine": "Holders",
  "summary": "Reads a Solana token's holder count, 24h holder change, how much the top holders own, and whether mint and freeze authority are switched off.",
  "job": "Read a token's holders",
  "category": "tokens",
  "chains": ["solana"],
  "version": "1.0.0",
  "author": "Shelfwise",
  "license": "MIT",
  "price": { "type": "free" },
  "entry": "scripts/holders.mjs",
  "runtime": "Node 18+ or Bun, no dependencies",
  "permissions": {
    "network": ["lite-api.jup.ag"],
    "keys": [],
    "env": ["SOLANA_RPC_URL (optional: your own RPC, adds the top 20 holder accounts)"],
    "wallet": "none",
    "filesystem": "none"
  },
  "sources": [
    { "name": "Jupiter Tokens API v2", "url": "https://dev.jup.ag/docs/token-api/v2" },
    { "name": "Solana RPC: getTokenLargestAccounts (optional)", "url": "https://solana.com/docs/rpc/http/gettokenlargestaccounts" }
  ],
  "ask": "How many holders does JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN have, and how concentrated is it?"
}

MIT License

Copyright (c) 2026 Shelfwise

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

// Token holders: holder count and concentration for a Solana token. Zero dependencies.
import { pathToFileURL } from "node:url";

const JUP = "https://lite-api.jup.ag";
const MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const num = (v) => (v === null || v === undefined || !Number.isFinite(Number(v)) ? null : Number(v));

async function rpc(url, method, params) {
  const res = await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
  });
  const body = await res.json().catch(() => null);
  if (!res.ok || body?.error) throw new Error(body?.error?.message ?? `RPC answered ${res.status}`);
  return body.result;
}

async function largestAccounts(rpcUrl, mint, supply) {
  const largest = await rpc(rpcUrl, "getTokenLargestAccounts", [mint]);
  const accounts = (largest?.value ?? []).slice(0, 20);
  const infos = await rpc(rpcUrl, "getMultipleAccounts", [accounts.map((a) => a.address), { encoding: "jsonParsed" }]);
  return accounts.map((a, i) => {
    const amount = num(a.uiAmountString ?? a.uiAmount);
    return {
      rank: i + 1,
      tokenAccount: a.address,
      owner: infos?.value?.[i]?.data?.parsed?.info?.owner ?? null,
      amount,
      pctOfSupply: supply && amount !== null ? (amount / supply) * 100 : null,
    };
  });
}

export async function holders(mint, { rpcUrl = process.env.SOLANA_RPC_URL } = {}) {
  if (!MINT_RE.test(String(mint ?? ""))) throw new Error("Usage: holders.mjs <mint address>");
  const res = await fetch(`${JUP}/tokens/v2/search?query=${mint}`, { headers: { accept: "application/json" } });
  if (!res.ok) throw new Error(`Jupiter answered ${res.status}`);
  const list = await res.json();
  const t = (Array.isArray(list) ? list : []).find((x) => x?.id === mint);
  if (!t) throw new Error(`Jupiter has no data for mint ${mint}`);

  let largest = null;
  let largestError = null;
  if (rpcUrl) {
    try {
      largest = await largestAccounts(rpcUrl, mint, num(t.totalSupply));
    } catch (e) {
      largestError = String(e?.message ?? e);
    }
  }
  return {
    source: rpcUrl ? "jupiter + your RPC" : "jupiter",
    fetchedAt: new Date().toISOString(),
    mint,
    symbol: t.symbol ?? null,
    name: t.name ?? null,
    holderCount: num(t.holderCount),
    holderChange24hPct: num(t.stats24h?.holderChange),
    topHoldersPct: num(t.audit?.topHoldersPercentage),
    devMints: num(t.audit?.devMints),
    mintAuthorityDisabled: t.audit?.mintAuthorityDisabled ?? null,
    freezeAuthorityDisabled: t.audit?.freezeAuthorityDisabled ?? null,
    organicScore: num(t.organicScore),
    isVerified: t.isVerified ?? null,
    totalSupply: num(t.totalSupply),
    largest,
    ...(largestError ? { largestError } : {}),
  };
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  holders(process.argv[2])
    .then((r) => console.log(JSON.stringify(r, null, 2)))
    .catch((e) => {
      console.log(JSON.stringify({ error: String(e?.message ?? e) }));
      process.exit(1);
    });
}

// Self-test against a long-lived token (JUP on Solana). Run: node test.mjs
import { pathToFileURL } from "node:url";
import { holders } from "./scripts/holders.mjs";

export default async function test() {
  const r = await holders("JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN", { rpcUrl: "" });
  const checks = [];
  const check = (name, ok) => checks.push({ name, ok: Boolean(ok) });
  check("finds the token", r.symbol === "JUP");
  check("has a holder count", r.holderCount > 1000);
  check("top holder share is a percentage", r.topHoldersPct === null || (r.topHoldersPct >= 0 && r.topHoldersPct <= 100));
  check("reports mint authority", typeof r.mintAuthorityDisabled === "boolean");
  check("skips the RPC list without SOLANA_RPC_URL", r.largest === null);
  let rejected = false;
  try { await holders("not-a-mint"); } catch { rejected = true; }
  check("rejects a malformed mint", rejected);
  return { ok: checks.every((c) => c.ok), checks };
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  test().then((r) => { console.log(JSON.stringify(r, null, 2)); process.exit(r.ok ? 0 : 1); },
    (e) => { console.log(JSON.stringify({ ok: false, error: String(e?.message ?? e) })); process.exit(1); });
}