Pro and above · ranked depth depends on plan · Compare plans and subscribe
Keep Solana top holder rankings in sync
Build a live Solana holder table from an indexed REST snapshot and WebSocket rankings. Handle rank changes, stale data and index rebuilds.
By MadeOnSol · Updated
Integration choice
Use REST for the first paint and the holder channel’s snapshot as the baseline for live updates. Each accepted update carries the complete disclosed ranking. Replacing that list removes wallets that left the top ranks and preserves the index’s ordering.
Before you start
- Use a server-side API key and a mint with holder-index coverage.
- Keep raw balances as integer strings or BigInt. Prepare a token switch and a reconnect in the test client.
Implementation steps
- Set SOLANA_MINT to a covered mint and fetch the indexed snapshot on your backend. Inspect source.method and index.status before using the rows. A census fallback is a separate observation.
- Subscribe to token:holders_top for the same mint. Track the holder payload’s mint, epoch and seq separately from the outer connection cursor. Install the channel snapshot before applying updates.
- Within one epoch ignore older snapshots and repeated updates. Replace the top array on a newer valid update, including when updates were coalesced. Publish rows, count and finalized slot together.
- On an epoch change or resync_required, wait for a new snapshot. If retaining the last verified view, keep its original timestamp and freshness state. A late REST response must not overwrite a newer stream snapshot.
What happens when a wallet leaves the top ranks?
In a three-row example, B can disappear because D overtook it. B may still own tokens. Replace the ordered list, key the display rows by owner and use the reported holder count for the population. Adding D to the old array would leave a plausible but incorrect fourth row.
Separate the last change from the last verification
A quiet token can keep the same ranking while its finalized verification slot advances. A heartbeat can advance verification for the current epoch. If it advertises a sequence ahead of your applied state, request a fresh snapshot. A stale frame carries the last verified observation. Record its age instead of stamping it with the current time.
Choose the right denominator and depth
The indexed ranking aggregates token accounts by owner. Pro exposes up to 10 rows, Ultra 50 and Business 100. The sum of these balances describes the disclosed slice. For a percentage of supply, use supply verified for that mint and slot. Leave the share unknown when the denominator is unavailable.
Code examples
Subscribe on an authenticated Node.js socket
const token = process.env.SOLANA_MINT;
if (!token) throw new Error("Set SOLANA_MINT first");
socket.send(JSON.stringify({
type: "subscribe",
sub_id: "solana-live-holder-rankings",
channels: ["token:holders_top"],
filters: { mints: [token] }
}));Read the indexed ranking (server-side shell)
curl -H "Authorization: Bearer $MADEONSOL_API_KEY" "https://madeonsol.com/api/v1/tokens/$SOLANA_MINT/holders?source=index"Common mistakes and fixes
| Mistake | Recommended fix |
|---|---|
| A wallet appears twice after a rank change. | Replace the ordered rows atomically and use the owner as the display key. |
| A rebuild freezes the view. | Reset the epoch baseline on a new snapshot. Sequences from separate epochs cannot be compared. |
Verify your integration
Replay a three-row snapshot A/B/C, a newer update D/A/C, then the original snapshot in the same epoch. The final ordering must remain D/A/C. Repeat with a new epoch and with a heartbeat ahead of the applied sequence. Both cases need a new baseline.
Production checklist
- An older HTTP response cannot overwrite the stream.
- A departed rank leaves the table.
- A stale observation retains its verification time.
Frequently asked questions
Can a holder sequence skip a number?
Yes. A valid, newer full-ranking update can cover coalesced changes. A heartbeat alone cannot reconstruct missing rows.
Does an uncovered mint have zero holders?
Coverage describes the index. Inspect the response source and keep the holder count unknown unless a source measured it.
