# Track a token's holder count over time

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

Source: https://docs.crius.sh/guides/track-holder-count/ · Updated 2026-10-28

Short answer

Call `GET /v1/robinhood/token/{address}/holders/history?interval=1h` (Starter plan, 10 credits). It returns parallel arrays per interval: `t`, `holders` (count at the end), `min`, `max`, `new` and `exited`, plus a `summary` with the period's `min`, `max` and `now`. `min_usd` or `min_balance` set who counts as a holder.

[GET `/token/{address}/holders/history`](https://docs.crius.sh/reference/holders/holder-count-history/) [GET `/token/{address}/holders`](https://docs.crius.sh/reference/holders/live-holders/)

Holder count history is the number of addresses holding a token, measured over time at the interval you choose. Crius replays every transfer of the token and, for each interval, returns the count at its end, the lowest and highest count during it, and how many wallets arrived and left. You decide who counts as a holder: any balance, a minimum USD value or a minimum token amount.

## Get the history in one call

Example [Starter plan · 10 credits](https://docs.crius.sh/reference/holders/holder-count-history/)

### CHARGE's first five days: from 476 holders to 294

How did the number of Charge AI (0x7b8892cea949bc60d494681d1bc3ea96071ab0b8) holders change day by day after its launch?

GET/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/history?interval=1d&limit=5

 

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/history?interval=1d&limit=5" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/history?interval=1d&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/history?interval=1d&limit=5",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

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

```json
{
  "data": {
    "exited": [
      3082,
      1030,
      462,
      216,
      148
    ],
    "history": "complete",
    "holder_definition": {
      "exclude": [],
      "min_balance": null,
      "min_usd": null,
      "note": ""
    },
    "holders": [
      421,
      381,
      359,
      309,
      294
    ],
    "interval": "1d",
    "max": [
      476,
      429,
      382,
      359,
      313
    ],
    "min": [
      1,
      378,
      353,
      306,
      294
    ],
    "new": [
      3503,
      990,
      440,
      166,
      133
    ],
    "summary": {
      "max": 476,
      "max_ts": 1791936000000,
      "min": 1,
      "min_ts": 1791936000000,
      "now": 238
    },
    "t": [
      1791936000000,
      1792022400000,
      1792108800000,
      1792195200000,
      1792281600000
    ]
  },
  "meta": {
    "block": 100406819,
    "block_age_ms": 372,
    "block_ts": 1793225080000,
    "chain": "robinhood",
    "finalized_block": 100397649,
    "lag_ms": 41,
    "safe_block": 100401329
  }
}
```

What this tells you

-   `interval: "1d"`: each array index is one UTC day. `t[0]` is 1791936000000 (2026-10-14, launch day) and `t[4]` 1792281600000 (2026-10-18). The captured example is cut to the first five days.
-   Launch day: `min[0]: 1` (right after the mint, the whole supply sat in one address), `max[0]: 476`, and the day closed at `holders[0]: 421`.
-   `new[0]: 3503` and `exited[0]: 3082`: thousands of wallets bought and sold out on the first day. That’s what launch-day flipping looks like.
-   From day 2 the count only fell: 381, 359, 309, 294. On each of those days `exited` was higher than `new` (1030 against 990 on day 2, 148 against 133 on day 5).
-   `summary.max: 476` at `max_ts: 1791936000000` is the peak of the whole history; `summary.now: 238` holders at capture, half the peak.
-   `holder_definition` has no `min_balance`, `min_usd` or `exclude`: every address with a balance counts, including pools and the burn address. Add `exclude=infra` to leave them out.

[Holder count history reference](https://docs.crius.sh/reference/holders/holder-count-history/) [Data looks wrong? Report it](mailto:support@crius.sh?subject=Wrong%20data%20in%20docs%20example%3A%20CHARGE's%20first%20five%20days%3A%20from%20476%20holders%20to%20294&body=Page%3A%20https%3A%2F%2Fdocs.crius.sh%2Fguides%2Ftrack-holder-count%2F%23charge-holder-history%0ARequest%3A%20GET%20%2Fv1%2Frobinhood%2Ftoken%2F0x7b8892cea949bc60d494681d1bc3ea96071ab0b8%2Fholders%2Fhistory%3Finterval%3D1d%26limit%3D5%0A%0AWhat's%20wrong%20or%20missing%3F%0A%0A)

The arrays add up: each day’s closing count is the previous close plus `new` minus `exited` (421 + 990 − 1030 = 381).

## What the fields mean

| Field | Meaning |
| --- | --- |
| `interval` | Bucket size: `1m`, `5m`, `15m`, `1h` (default), `4h` or `1d`. |
| `t[]` | Start of each interval, unix ms. |
| `holders[]` | Holder count at the end of the interval. |
| `min[]`, `max[]` | Lowest and highest count during the interval. |
| `new[]`, `exited[]` | Addresses that became holders, and that stopped being holders, during the interval. |
| `summary.min`, `min_ts`, `max`, `max_ts` | Lowest and highest count in the window, and the interval where each happened. |
| `summary.now` | The count at the end of the window. |
| `holder_definition` | Who counts: `min_balance`, `min_usd`, `exclude`, and a `note` (for example that `min_usd` was converted at the current price). |
| `history` | `complete` when the token's whole transfer history is indexed. |

`from` and `to` limit the window, with the same point forms as snapshots: `block:N`, `ts:MS`, `mcap:USD`, or the labels `launch`, `graduation`, `ath`, `now` (see [historical holders](https://docs.crius.sh/guides/get-historical-holders/#choose-the-point-in-time)). For example `from=graduation&to=now&interval=4h` charts holders since the token left its bonding curve. Intervals with no transfers are left out, so the `t` array can skip time.

## Use it in your app

1.  **Choose an interval for the chart’s range.** `1h` for a few days, `1d` for weeks. Finer intervals return more points for the same window.
    
2.  **Decide who counts.** The raw count includes every dust wallet, pools and the burn address. For a number users trust, use `exclude=infra` and a small `min_usd`, and say so on the chart.
    
3.  **Plot `holders` as the line and `min`/`max` as the band.** On busy days the count moves a lot inside one interval; the band shows it. Bars of `new` and `exited` explain the moves.
    
4.  **Get a Starter key.** Holder history needs the Starter plan and costs 10 credits per call. Past intervals don’t change, so fetch the full history once and then only the recent window.
    

```python
import os, requests
from datetime import datetime, timezone

token = "0x7b8892cea949bc60d494681d1bc3ea96071ab0b8"
r = requests.get(
    f"https://api.crius.sh/v1/robinhood/token/{token}/holders/history",
    params={"interval": "1d", "from": "launch", "to": "now", "exclude": "infra", "min_usd": 1},
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
d = r.json()["data"]
for t, n, new, out in zip(d["t"], d["holders"], d["new"], d["exited"]):
    day = datetime.fromtimestamp(t / 1000, timezone.utc).date()
    print(day, n, f"+{new}", f"-{out}")
s = d["summary"]
print(f"peak {s['max']}, now {s['now']} ({s['now'] / s['max']:.0%} of peak)")
```

Very active tokens

Holder history replays every transfer of the token. Tokens with more than 2M transfers (WETH, USDG, tokenized stocks) return `400 window_too_large` (or `token_too_active`). For those, poll the live [`/holders`](https://docs.crius.sh/reference/holders/live-holders/) `count` on a schedule instead.

## Frequently asked questions

**How do I get a token's holder count history?**

Call `/v1/robinhood/token/{address}/holders/history` with an `interval` (`1m`, `5m`, `15m`, `1h`, `4h`, `1d`). Each index `i` of the arrays is one interval starting at `t[i]` (unix ms): `holders[i]` is the count at its end, `min[i]` and `max[i]` the lowest and highest during it, `new[i]` and `exited[i]` the wallets that arrived and left.

**What was the most holders a token ever had?**

`summary.max` and `summary.max_ts` give the highest count in the window and when it happened; `summary.min` and `min_ts` the lowest; `summary.now` the current count. For CHARGE, the peak was 476 on launch day and the count at capture was 238.

**Can I ignore dust wallets in the holder count?**

Yes. `min_usd=10` counts only wallets holding $10 or more, `min_balance` a token amount. `min_usd` is converted to a token amount at the current price (`holder_definition.note` says so), so the threshold is the same token amount across the whole chart.

**Why are new and exited holders so high on launch day?**

Arrivals and exits both rise with volume. On CHARGE's first day 3,503 wallets became holders and 3,082 left the same day; quick flippers and bots inflate both. Watch `new` against `exited` rather than the count alone.

**Which plan does holder history need?**

The Starter plan or higher, 10 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 **Historical holders** 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. Read](https://docs.crius.sh/guides/get-historical-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 **Chain stats dashboard** Build a Robinhood Chain analytics dashboard with the Crius API: DEX volume, trades, TVL, launches, gas and volume history in your time zone, with code. Read](https://docs.crius.sh/guides/build-a-chain-stats-dashboard/) [API reference **Holder count history API** Holder count over time at a chosen interval, with your own definition of a holder (min\_balance or min\_usd). Read](https://docs.crius.sh/reference/holders/holder-count-history/)