Holders & traders

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	`GET /v1/{chain}/token/{address}/holders`	Free	2
Holder snapshot	`GET /v1/{chain}/token/{address}/holders/snapshot`	Free	5
Holder cohort	`GET /v1/{chain}/token/{address}/holders/cohort`	Starter	10
Holder count history	`GET /v1/{chain}/token/{address}/holders/history`	Starter	10
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 "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders?limit=20" \
  -H "x-api-key: $CRIUS_API_KEY"

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();

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

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();

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

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();

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 "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders/history?interval=1h&from=launch&to=now" \
  -H "x-api-key: $CRIUS_API_KEY"

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();

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 "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/traders?sort=pnl&window=all&limit=20" \
  -H "x-api-key: $CRIUS_API_KEY"

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();

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

Crius · Changelog · Status · llms.txt · Terms · Privacy

Questions? support@crius.sh