# Holders & traders

> Live holder lists, holder snapshots at any past block, time or market cap, diamond-hand cohorts, holder count history and top traders with PnL.

Source: https://crius.sh/docs/reference/holders/

Holder data for every ERC-20 on the chain, live and historical.

Points in time (`at`, `from`, `to`) accept 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\|last\|ath`) |
| `launch`, `graduation`, `ath`, `now` | lifecycle labels |

| Endpoint | Method | Plan | Credits |
|---|---|---|---|
| [Live holders](#live-holders) | `GET /v1/{chain}/token/{address}/holders` | Free | 2 |
| [Holder snapshot](#holder-snapshot) | `GET /v1/{chain}/token/{address}/holders/snapshot` | Free | 5 |
| [Holder cohort](#holder-cohort) | `GET /v1/{chain}/token/{address}/holders/cohort` | Starter | 10 |
| [Holder count history](#holder-count-history) | `GET /v1/{chain}/token/{address}/holders/history` | Starter | 10 |
| [Top traders](#top-traders) | `GET /v1/{chain}/token/{address}/traders` | Free | 5 |

## Live holders

**GET** `/v1/{chain}/token/{address}/holders`

**Plan:** Free and above · **Cost:** 2 credits per call

The current holder list, ranked by balance, with each holder's share of supply, USD value and labels (pools, lockers, burn addresses, the dev). Also returns the holder count and top-10 concentration.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `limit` | query | integer | `100` | Maximum number of items to return. Up to 500. |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders?limit=20" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

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

### Key response fields

- `count`, `top10_pct`
- `holders[]`: `rank`, `address`, `balance`, `pct`, `value_usd`, `value_eth`, `label`

## Holder snapshot

**GET** `/v1/{chain}/token/{address}/holders/snapshot`

**Plan:** Free and above · **Cost:** 5 credits per call

Holders **as they were at a past point**, valued at that moment's price. `compare_to=now` adds each holder's balance change since then, which answers "who bought before $50k market cap, and are they still holding?".

> Valued at that moment's price; compare_to=now adds change per holder.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `at` | query | string | `trading_open` | The point in time to look at (see the forms above). One of `block:N`, `ts:MS`, `mcap:USD`, `launch`, `trading_open`, `graduation`, `ath`, `now`. |
| `mcap_crossing` | query | string | `first` | Which crossing of the market cap level to use. One of `first`, `last`. |
| `compare_to` | query | string | `now` | Add each holder's change since another point (`now` or any `at` form). |
| `exclude` | query | string |  | Comma list of holder classes to leave out, such as `infra` (pools, lockers, burn) or `bots`. |
| `min_usd` | query | number |  | Only items worth at least this many USD. |
| `min_pct` | query | number |  | Minimum share of supply, in percent. |
| `tag` | query | string |  | Only wallets with this tag (`sniper`, `bot`, `whale`, `fresh`, `dev`, `insider`, `bundler`, `top_trader`). |
| `limit` | query | integer | `100` | Maximum number of items to return. |
| `cursor` | query | string |  | Pagination cursor from the previous response's `meta.next_cursor`. |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/snapshot?at=mcap%3A50000&compare_to=now&exclude=infra" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/snapshot?at=mcap%3A50000&compare_to=now&exclude=infra", {
  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=mcap%3A50000&compare_to=now&exclude=infra",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

## Holder cohort

**GET** `/v1/{chain}/token/{address}/holders/cohort`

**Plan:** Starter and above · **Cost:** 10 credits per call

Wallets that held through a window. A holder qualifies when it stayed above a size threshold (`min_usd`, `min_balance` or `min_pct`); with `continuous=true` it must hold for the whole window, and `reset_on` decides what breaks continuity (`sell` by default). `entered_before=mcap:20000` keeps only wallets that first qualified before that point. Sort by hold time, balance, entry market cap or PnL.

> Continuity with reset on sell / decrease / below threshold.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `from` | query | string | `trading_open` | Start of the window (`block:`, `ts:`, `mcap:` or a label). |
| `to` | query | string | `now` | End of the window (same forms as `from`). |
| `min_usd` | query | number | `50` | Only items worth at least this many USD. |
| `min_balance` | query | number |  | Minimum balance in token units. |
| `min_pct` | query | number |  | Minimum share of supply, in percent. |
| `continuous` | query | boolean | `false` | `true`: the holder must stay above the threshold for the whole window. |
| `reset_on` | query | string | `sell` | One of `sell`, `any_decrease`, `below_threshold`, `none`. |
| `min_hold_s` | query | integer |  | Minimum continuous hold time inside the window, in seconds. |
| `entered_before` | query | string |  | Only holders that first qualified before this point (e.g. `mcap:20000`). |
| `exclude` | query | string |  | Comma list of holder classes to leave out, such as `infra` (pools, lockers, burn) or `bots`. Comma list of `infra`, `dev`, `snipers`. |
| `sort` | query | string | `hold_time` | Sort order. One of `hold_time`, `balance`, `entry_mcap`. |
| `limit` | query | integer | `100` | Maximum number of items to return. |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/cohort?from=mcap%3A10000&to=now&min_usd=50&continuous=true&reset_on=sell&exclude=infra" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/cohort?from=mcap%3A10000&to=now&min_usd=50&continuous=true&reset_on=sell&exclude=infra", {
  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/cohort?from=mcap%3A10000&to=now&min_usd=50&continuous=true&reset_on=sell&exclude=infra",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

## Holder count history

**GET** `/v1/{chain}/token/{address}/holders/history`

**Plan:** Starter and above · **Cost:** 10 credits per call

Holder count over time at a chosen interval, with your own definition of a holder (`min_balance` or `min_usd`). Answers "what was the minimum and maximum number of holders during a period".

> min / max / new / exited per interval.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `interval` | query | string | `1h` | Bucket size. One of `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. |
| `from` | query | string |  | Start of the window (`block:`, `ts:`, `mcap:` or a label). |
| `to` | query | string |  | End of the window (same forms as `from`). |
| `min_balance` | query | number |  | Minimum balance in token units. |
| `min_usd` | query | number |  | Only items worth at least this many USD. |
| `exclude` | query | string |  | Comma list of holder classes to leave out, such as `infra` (pools, lockers, burn) or `bots`. |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/history?interval=1h&from=launch&to=now" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

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

## Top traders

**GET** `/v1/{chain}/token/{address}/traders`

**Plan:** Free and above · **Cost:** 5 credits per call

Traders of the token ranked by PnL, realized PnL, volume, buys or ROI over a window (`1h`, `24h`, `7d`, `all`), with wallet tags (`sniper`, `bot`, `whale`, `dev`…).

> Average cost; USD at trade time; unrealized at current price.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `sort` | query | string | `pnl` | Sort order. One of `pnl`, `realized_pnl`, `volume`, `buys`, `roi`. |
| `window` | query | string | `all` | Stats window. One of `1h`, `24h`, `7d`, `all`. |
| `tag` | query | string |  | Only wallets with this tag (`sniper`, `bot`, `whale`, `fresh`, `dev`, `insider`, `bundler`, `top_trader`). |
| `limit` | query | integer | `50` | Maximum number of items to return. |
| `cursor` | query | string |  | Pagination cursor from the previous response's `meta.next_cursor`. |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/traders?sort=pnl&window=all&limit=20" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

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