CRIUS Docs
API status Get API key
Holders & wallets

Get a token's holders at a past block, time or market cap

Get a Robinhood Chain token's holders at any past block, time, market cap or launch stage, valued at that moment's price, with cost basis per holder.

Updated 3 min read
Short answer

Call GET /v1/robinhood/token/{address}/holders/snapshot?at=… (Free plan, 5 credits). at takes block:N, ts:MS, mcap:USD or a label (launch, graduation, ath, now). It returns the holders at that block with balance, pct, value_usd at that moment's price, cost_basis_usd, unrealized_pnl_usd and tags; compare_to=now adds each holder's change since.

GET /token/{address}/holders/snapshot GET /token/{address}/holders GET /token/{address}/holders/cohort

A holder snapshot is the list of a token’s holders as it was at one moment in the past: a block, a time, the block where the market cap first crossed a level, or a lifecycle event such as graduation. Crius rebuilds every balance at that block from the token’s full transfer history and values it at the price of that moment, so you can answer “who held this before $50k?” or “what did the top of the list look like a week ago?” in one call.

Choose the point in time

at (and from / to on the cohort and history endpoints) accepts several forms:

Form Meaning
block:95000000 an exact L2 block
ts:1792000000000 the last block at or before that time (unix ms)
mcap:50000 the block where market cap first crossed $50k (mcap_crossing=first or last)
launch, graduation, ath, now lifecycle labels

A point that never happened for the token (a market cap it never reached, graduation for a token that didn’t graduate) returns 404 point_not_found; one that can’t be parsed returns 400 invalid_at. See Errors.

Get the holders one week ago

Example Free plan · 5 credits

CHARGE holders one week before capture: 203 holders, $6,033 total

Who held Charge AI (0x7b8892cea949bc60d494681d1bc3ea96071ab0b8) on 2026-10-21 at 22:04 UTC, and were they in profit?

GET/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/snapshot?at=ts:1792620279327&limit=5
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/snapshot?at=ts:1792620279327&limit=5" \
  -H "x-api-key: $CRIUS_API_KEY"
Real response 200 Captured Oct 28, 2026 · 106 lines (arrays trimmed) 
{
  "data": {
    "distribution": {
      "top10_ex_infra_pct": 20.2394,
      "top10_incl_infra_pct": 88.256,
      "top10_pct": 20.2394
    },
    "history": "complete",
    "holders": [
      {
        "address": "0x8366a39cc670b4001a1121b8f6a443a643e40951",
        "balance": 599611856.72294939695548577,
        "cost_basis_usd": null,
        "label": "uniswap_v4_pool_manager",
        "pct": 59.9612,
        "rank": 1,
        "tags": [
          "pool"
        ],
        "unrealized_pnl_usd": null,
        "value_eth": 1.4505,
        "value_usd": 3617.23
      },
      {
        "address": "0x267444d099b10fb5ed7c3cc7b7c767adca574952",
        "balance": 81632653.061224486519511236,
        "cost_basis_usd": null,
        "label": "pons_v2_launch_locker",
        "pct": 8.16327,
        "rank": 2,
        "tags": [
          "lp_locker"
        ],
        "unrealized_pnl_usd": null,
        "value_eth": 0.197474,
        "value_usd": 492.459
      },
      {
        "address": "0xcae68632857541d7b625f5af57149a77c80b15f7",
        "balance": 40394446.124537182821971423,
        "cost_basis_usd": 437.688,
        "label": null,
        "pct": 4.03944,
        "rank": 3,
        "tags": [
          "smart_account",
          "fomo"
        ],
        "unrealized_pnl_usd": -194.003,
        "value_eth": 0.0977165,
        "value_usd": 243.684
      },
      {
        "address": "0xe683eb5c66b0c55c54ce45d46a3bf0a69d809c8f",
        "balance": 29879481.370714222341354462,
        "cost_basis_usd": 515.975,
        "label": null,
        "pct": 2.98795,
        "rank": 4,
        "tags": [
          "smart_account"
        ],
        "unrealized_pnl_usd": -335.724,
        "value_eth": 0.0722802,
        "value_usd": 180.252
      },
      {
        "address": "0x000000000000000000000000000000000000dead",
        "balance": 29840058.774195638068253872,
        "cost_basis_usd": null,
        "label": "burn",
        "pct": 2.98401,
        "rank": 5,
        "tags": [
          "burn"
        ],
        "unrealized_pnl_usd": null,
        "value_eth": 0.0721848,
        "value_usd": 180.014
      }
    ],
    "holders_count": 203,
    "price_at_snapshot": {
      "eth": 0.00000000241906,
      "eth_usd": 2493.79,
      "usd": 0.00000603262
    },
    "snapshot": {
      "at": "ts:1792620279327",
      "block": 94616288,
      "ts": 1792620279800
    },
    "token": "0x7b8892cea949bc60d494681d1bc3ea96071ab0b8",
    "total_value_usd": 6032.62
  },
  "meta": {
    "block": 100406812,
    "block_age_ms": 701,
    "block_ts": 1793225079000,
    "chain": "robinhood",
    "finalized_block": 100397649,
    "lag_ms": 38,
    "next_cursor": "5",
    "safe_block": 100401329
  }
}

What this tells you

  • snapshot.at: "ts:1792620279327" resolved to snapshot.block: 94616288 (snapshot.ts: 1792620279800), the last block at or before that time.
  • price_at_snapshot.usd was 0.00000603262 with ETH at eth_usd: 2493.79. At that price every token held was worth total_value_usd: 6032.62.
  • holders_count: 203 then, against 178 in the live list a week later.
  • distribution.top10_pct: 20.2394 (the same as top10_ex_infra_pct) versus top10_incl_infra_pct: 88.256: counting the pool, the locker and the burn address would make the token look nearly 90% concentrated.
  • Rank 3, 0xcae68632857541d7b625f5af57149a77c80b15f7, is tagged smart_account and fomo (a FOMO app wallet). It held 4.03944% worth $243.684 against a cost_basis_usd of 437.688: unrealized_pnl_usd: -194.003 at that moment.
  • Infrastructure has cost_basis_usd: null and unrealized_pnl_usd: null: the PoolManager (tags: ["pool"], 59.9612% then) never bought anything.
  • meta.next_cursor: "5": pass cursor=5 for the next page.
Holder snapshot reference Data looks wrong? Report it

What the fields mean

FieldMeaning
snapshot.at, block, tsWhat you asked for, and the block and timestamp it resolved to.
price_at_snapshot.usd, eth, eth_usdThe token's price at that block and the ETH/USD rate used for value_eth.
holders_countAddresses with a balance at that block.
total_value_usdEvery balance at that block valued at price_at_snapshot.usd.
distribution.top10_pctTop-10 share without infrastructure (same as top10_ex_infra_pct).
distribution.top10_incl_infra_pctTop-10 share counting pools, lockers and burn addresses.
holders[].balance, pct, rankBalance, share of supply and rank at that block.
holders[].value_usd, value_ethThe balance valued at that moment's price.
holders[].cost_basis_usdWhat the holder paid for that balance: its average buy price from trades up to the snapshot, times the balance. null when it never bought (infrastructure, tokens received by transfer).
holders[].unrealized_pnl_usdvalue_usd minus cost_basis_usd at that moment.
holders[].tags, labelWallet tags (pool, lp_locker, burn, smart_account, fomo…) and the known name of the address.
historycomplete when the token's whole transfer history is indexed.

Filters: exclude=infra drops pools, lockers and burn addresses from the list, tag keeps only holders with one tag (for example tag=smart_account), and min_usd / min_pct hide small holders. limit takes up to 500 per page.

Compare then and now

compare_to=now adds each holder’s balance change between the snapshot and now. It answers the question traders ask most: of the wallets that held at a given point, who is still in? You can also compare two past points, for example at=launch&compare_to=graduation.

A quick read of the example without compare_to: 0xcae68632857541d7b625f5af57149a77c80b15f7 held 4.04% a week before capture. In the live wallets-only list a week later, the fifth-largest holder has 1.22147% and that wallet isn’t in the top five. So it now holds under 1.23%: it sold or moved more than two thirds of its position. compare_to=now would give the exact change instead of this inference.

Use it in your app

  1. Pick the point in the form your users think in. A chart click gives you a timestamp (ts:), a “before the pump” filter gives a market cap (mcap:), and “launch buyers” maps to launch. Read back snapshot.block to show what the point resolved to.

  2. Leave infrastructure out. Add exclude=infra unless you want the pool and locker rows; top10_pct already excludes them either way.

  3. Show profit at that moment. cost_basis_usd and unrealized_pnl_usd tell you who was in profit at the snapshot, which is often more useful than who was big.

  4. Budget for it. Each call costs 5 credits on the Free plan or higher. A past snapshot never changes, so cache it by token and snapshot.block.

import os, requests


token = "0x7b8892cea949bc60d494681d1bc3ea96071ab0b8"
r = requests.get(
    f"https://api.crius.sh/v1/robinhood/token/{token}/holders/snapshot",
    params={"at": "mcap:50000", "exclude": "infra", "limit": 50},
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
d = r.json()["data"]
print(f"block {d['snapshot']['block']}: {d['holders_count']} holders, price ${d['price_at_snapshot']['usd']}")
for h in d["holders"]:
    pnl = h["unrealized_pnl_usd"]
    print(h["rank"], h["address"], f"{h['pct']}%", "in profit" if pnl and pnl > 0 else "", h["tags"])

Frequently asked questions

How do I see who held a token before it pumped?

Take a snapshot at the market cap before the run: /holders/snapshot?at=mcap:50000&compare_to=now&exclude=infra. mcap:50000 resolves to the block where the market cap first crossed $50k, and compare_to=now shows, for each of those holders, how their balance changed since.

What does `ts:` resolve to?

The last block at or before that time, in unix milliseconds. In the example, ts:1792620279327 resolved to block 94616288, whose timestamp is 1792620279800. The resolved block and its time are returned in snapshot.block and snapshot.ts, so you always know exactly which state you got.

Is the USD value historical or current?

Historical. value_usd and total_value_usd use the token's price at the snapshot block (price_at_snapshot.usd, from the last trade of $1 or more at or before it), and value_eth uses that moment's ETH/USD (price_at_snapshot.eth_usd).

Can I take a snapshot of WETH or USDG?

Not at a past block. A snapshot replays every transfer of the token up to that point, and tokens with more than 2M transfers (WETH, USDG, tokenized stocks) return 400 window_too_large. at=now still works for them, as does the live /holders list.

Which plan does the holder snapshot need?

The Free plan (a free API key), 5 credits per call. See Plans & limits.

Guide Token holders Robinhood Chain token holders API: get any token's top holders in one call, with balance, share of supply, USD value, labels, holder count and top-10 share. Read Guide Diamond-hand holders Find wallets that bought a Robinhood Chain token early and held through the run, with hold time, entry market cap, sells and PnL per wallet. Real example. Read Guide Holder count history Chart a Robinhood Chain token's holder count over time: min, max, new and exited holders per interval, with your own definition of a holder. Real example. Read Concept Holder classes How the Crius API tells real holders from pools, the PoolManager, lockers and contracts, and how it tags devs, snipers, whales and smart accounts. Read API reference Holder snapshot API Holders as they were at a past point, valued at that moment's price. Read

Get your free Crius API key

Every example on this page works with a free key: higher rate limits than the anonymous plan, holders, wallets and the WebSocket stream. No card needed.

Get a free API key See plans
  • Robinhood Chain (4663) only, from our own archive nodes
  • REST + WebSocket
  • Pay on-chain or by card