Cohorts and axes
How Hyperliquid wallets are bucketed: the axis and cohort ladders, the per-position tier ladder, and which axes can group.
Four query parameters recur across the HL Cohorts and Hyperliquid namespaces and mean specific things. Getting them wrong is the most expensive mistake available here, because most of the wrong answers are 200s.
This page covers axis and cohort; labelBasis and grading are on Label basis.
axis: which ladder buckets a wallet
The general routes accept size, pnl and pnl_abs;
/symbols/{symbol}/cohort-metrics accepts two
more, and /segments/{cohort}/history serves size
and pnl only.
| Axis | What it buckets | Where accepted |
|---|---|---|
size | Absolute-$ account-value tier. A stored column, so always point-in-time. | Everywhere an axis= exists |
pnl | Percentile rank of a wallet's cumulative realized PnL. A dictionary lookup, not a column; unknown below 10 closed trades. | Everywhere |
pnl_abs | The same cumulative realized PnL banded in dollars ($1m+ … <-$1m). Always resolved at query time — no frozen source exists. | Everywhere except /segments/{cohort}/history |
tier | The per-position notional bucket, derived from the row's size_usd. | /symbols/{symbol}/cohort-metrics only |
pnl_unrealized | Rank by unrealized PnL of open positions as a share of account value — "currently onside". | /symbols/{symbol}/cohort-metrics only |
trade_size | The name /segments gives the per-position ladder, with groupable: false. Rejected as axis= on every per-wallet route — a wallet straddles buckets; /symbols/{symbol}/cohort-metrics takes it as an alias of tier and answers axis: tier. Filter on the groupable field. | /symbols/{symbol}/cohort-metrics only, as an alias of tier |
pnl and pnl_abs band the same number and are not comparable
They are a re-labelling of one quantity, not two measurements — which is why the catalogue reports
a distinct basis string for each. One ladder's $100k-$1m and the other's smart are not the
same population. A client porting from a competitor whose PnL cohorts are absolute-dollar bands
must read /segments rather than assume the boundaries:
the bucket names are similar and the definitions are not. The unrealized-PnL ladder that used
to back axis=pnl was dropped 2026-08-03.
cohort: one bucket on that ladder
/cohorts returns the exact strings ?cohort= accepts, and
it is generated from the same label set ?cohort= is validated against, so a label listed there
is a label the parameter accepts. Slugs from /segments are
accepted too. The retired micro/small/medium/large/mega vocabulary is gone: sending one
gets a 400 naming its replacement rather than a generic refusal.
The tier ladder
axis=tier is the per-position ladder — each row's own notional bucket, derived from its
size_usd, largest first: >$2.5m, $1m-$2.5m, $500k-$1m, $250k-$500k, $100k-$250k,
$50k-$100k, $25k-$50k, $10k-$25k, $1k-$10k, <$1k. It is a grouping only here, because
this endpoint aggregates position rows and each row sits in exactly one bucket; the per-wallet
endpoints keep rejecting it.
pnl_unrealized ranks positioning, not skill
axis=pnl_unrealized grades positioning, not skill
axis=pnl_unrealized ranks positioning rather than skill. Each wallet is ranked by the unrealized
PnL of its open positions as a share of account value, over its last snapshot strictly before hour
H. That grading turns over about 44% of wallets per day against the realized ladder's 2.4%
— which is the point: it is a different axis, not a re-spelling. Twelve rungs, no unknown
(eligibility is a positive-equity snapshot, not a trade count), the same five null fields as
point-in-time pnl rows before 2026-08-07 (listed in unavailable_fields), coverage from 2026-04-04 with a known three-day hole (2026-06-28 to 06-30,
graded off days whose equity feed was down). It is hourly, and has been since the rollup moved
on 2026-08-19; anything describing it as a daily grading is stale.
Which axes can group
Filter on groupable
groupable is true for the per-wallet ladders and false for trade_size, which buckets a
position rather than a wallet and is rejected as ?axis= by
/heatmap and
/segments/{cohort}/summary. A client
generating code off /segments that assumes every published axis is a valid grouping key will
emit calls that 400.
Per-wallet ladders only — this groups wallets, and a wallet straddles position-size buckets. Check
the groupable field on /segments.
Before you rely on it
What the HL Cohorts field names do not tell you, the two label bases, the axes and the provisional newest row.
Point-in-time vs current labels
When a cohort label was computed: labelBasis, grading, the lookahead that breaks a backtest, and the endpoints that refuse or fix a basis.