Pro and above · Compare plans and subscribe
Reconcile Robinhood Chain holder counts and transfers
Build a Robinhood Chain holder panel that preserves measured zero, handles incomplete transfer history and compares balances at the reconciliation block.
By MadeOnSol · Updated
Integration choice
Use the REST holder book to inspect the indexed balance distribution and its supply reconciliation. Keep the count, the block through which transfers were scanned and the last supply check as separate observations. Use the chain-specific holder stream for subsequent updates.
Before you start
- Use a server-side key, an RHC token contract and an address with a known transfer history for comparison.
- Store token balances as exact integers. Keep chain and token address in every cache key.
Implementation steps
- Set RHC_ADDRESS to the token contract and read the first holders page. Save concentration.holder_count, holder_count_status, verified, reconciliation and source together.
- Compare recon_supply and chain_supply at reconciliation.recon_block. Preserve integer precision. Record source.scanned_to_block separately because transfer processing can advance after a supply check.
- Subscribe to rhc:token_holders for the address. Install the channel snapshot before consuming changes. Acknowledge a replacement snapshot by replacing local state. Keep REST pagination cursors separate from stream progress.
- If the stream signals incomplete coverage or changes move a wallet beyond the ranking you can prove, refresh the snapshot. Keep any previous verified observation dated and avoid filling missing counts from the number of rows.
How to interpret three real response shapes
A first page can report holder_count 0 with holder_count_status measured when only excluded pools or burn addresses hold the token. A first page with no positive indexed balances can return null with not_indexed. A later page whose underlying zero cannot establish either case can return null with unknown. A missing concentration object also leaves the count unavailable.
Reconcile supply before interpreting concentration
Use the reconciliation object to compare balances with on-chain total supply at the recorded block. Include pool and burn balances when reconciling the full supply. They are excluded from the circulating holder count. A top page is truncated and cannot prove a supply mismatch. Historical coverage and a matched supply check answer different questions. Preserve the reported history_coverage when present.
Trace a transfer through the holder book
Imagine A holds 5 units, B holds 7 and C holds zero. A sends 2 to B. The balances become 3 and 9 and the eligible holder count stays at two. If A then moves its remaining 3 to C, A exits and C enters, leaving the count at two again. This assumes ordinary eligible addresses. Prefer the reported post-change count when processing the stream.
Code examples
Subscribe on an authenticated Node.js socket
const token = process.env.RHC_ADDRESS;
if (!token) throw new Error("Set RHC_ADDRESS first");
socket.send(JSON.stringify({
type: "subscribe",
sub_id: "robinhood-chain-holder-reconciliation",
channels: ["rhc:token_holders"],
filters: { addresses: [token] }
}));Read the first holder page
curl -H "Authorization: Bearer $MADEONSOL_API_KEY" "https://madeonsol.com/api/v1/rhc/tokens/$RHC_ADDRESS/holders?limit=10"Three illustrative concentration fragments (JSON)
[
{
"holder_count": 0,
"holder_count_status": "measured"
},
{
"holder_count": null,
"holder_count_status": "not_indexed"
},
{
"holder_count": null,
"holder_count_status": "unknown"
}
]Common mistakes and fixes
| Mistake | Recommended fix |
|---|---|
| A later page appears to contain zero holders. | Read the count status and use the first page for interpretation. The page’s count field is the number of returned rows. |
| A REST cursor is used to resume the socket. | Use next_after to request the next REST page. Initialize live state from the stream’s snapshot. |
Verify your integration
Exercise the three concentration fragments below and assert three distinct UI states. Then process a transfer between two existing positive holders that leaves both balances positive. Balances can change without changing the count. Finally remove reconciliation evidence and verify the interface drops its verified claim.
Production checklist
- Missing history does not display as zero holders.
- Supply comparisons use the reconciliation block.
- A transfer with unchanged count still updates balances.
Frequently asked questions
Does a measured holder count prove full history?
It describes the count from the indexed balances. Check verification, reconciliation and available history coverage separately.
Is one holder one person?
The unit is a holder address. Smart accounts can hold tokens and one person may control several addresses.
