# 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.

Source: https://docs.crius.sh/guides/get-historical-holders/ · Updated 2026-10-28

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`](https://docs.crius.sh/reference/holders/holder-snapshot/) [GET `/token/{address}/holders`](https://docs.crius.sh/reference/holders/live-holders/) [GET `/token/{address}/holders/cohort`](https://docs.crius.sh/reference/holders/holder-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](https://docs.crius.sh/errors/).

## Get the holders one week ago

Example [Free plan · 5 credits](https://docs.crius.sh/reference/holders/holder-snapshot/)

### 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**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/snapshot?at=ts:1792620279327&limit=5" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/snapshot?at=ts:1792620279327&limit=5", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/snapshot?at=ts:1792620279327&limit=5",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

**Real response 200 Captured Oct 28, 2026 · 106 lines (arrays trimmed)**

```json
{
  "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](https://docs.crius.sh/guides/get-token-holders/#charge-holders) 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](https://docs.crius.sh/reference/holders/holder-snapshot/) [Data looks wrong? Report it](mailto:support@crius.sh?subject=Wrong%20data%20in%20docs%20example%3A%20CHARGE%20holders%20one%20week%20before%20capture%3A%20203%20holders%2C%20%246%2C033%20total&body=Page%3A%20https%3A%2F%2Fdocs.crius.sh%2Fguides%2Fget-historical-holders%2F%23snapshot-one-week%0ARequest%3A%20GET%20%2Fv1%2Frobinhood%2Ftoken%2F0x7b8892cea949bc60d494681d1bc3ea96071ab0b8%2Fholders%2Fsnapshot%3Fat%3Dts%3A1792620279327%26limit%3D5%0A%0AWhat's%20wrong%20or%20missing%3F%0A%0A)

## What the fields mean

| Field | Meaning |
| --- | --- |
| `snapshot.at`, `block`, `ts` | What you asked for, and the block and timestamp it resolved to. |
| `price_at_snapshot.usd`, `eth`, `eth_usd` | The token's price at that block and the ETH/USD rate used for `value_eth`. |
| `holders_count` | Addresses with a balance at that block. |
| `total_value_usd` | Every balance at that block valued at `price_at_snapshot.usd`. |
| `distribution.top10_pct` | Top-10 share without infrastructure (same as `top10_ex_infra_pct`). |
| `distribution.top10_incl_infra_pct` | Top-10 share counting pools, lockers and burn addresses. |
| `holders[].balance`, `pct`, `rank` | Balance, share of supply and rank at that block. |
| `holders[].value_usd`, `value_eth` | The balance valued at that moment's price. |
| `holders[].cost_basis_usd` | What 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_usd` | `value_usd` minus `cost_basis_usd` at that moment. |
| `holders[].tags`, `label` | Wallet tags (`pool`, `lp_locker`, `burn`, `smart_account`, `fomo`…) and the known name of the address. |
| `history` | `complete` 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`.
    

```python
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"])
```

Large tokens

A past snapshot replays every transfer of the token. Tokens with more than 2M transfers (WETH, USDG, tokenized stocks) return `400 window_too_large` for past points; use `at=now` or the live [`/holders`](https://docs.crius.sh/reference/holders/live-holders/) list for them.

## 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`](https://docs.crius.sh/reference/holders/live-holders/) list.

**Which plan does the holder snapshot need?**

The Free plan (a free API key), 5 credits per call. See [Plans & limits](https://docs.crius.sh/plans-and-limits/).

## Related

[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](https://docs.crius.sh/guides/get-token-holders/) [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](https://docs.crius.sh/guides/find-diamond-hand-holders/) [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](https://docs.crius.sh/guides/track-holder-count/) [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](https://docs.crius.sh/concepts/holder-classes/) [API reference **Holder snapshot API** Holders as they were at a past point, valued at that moment's price. Read](https://docs.crius.sh/reference/holders/holder-snapshot/)