Hyperliquid cohort data for AI agents: MCP, API, WebSocket and alerts

The canonical cohort ladders — label sets only, in axis order.

{"size": [...12], "pnl": [...12, "unknown"], "pnl_abs": [...8, "unknown"], "tier": [...10]} — the same sets the axes group by and the cohort filters validate against, so this endpoint cannot disagree with either: a label is served by its axis if and only if it is in this response, and ?cohort= accepts exactly these strings (or their /segments slugs). unknown rides the two PnL sets because it is a real, queryable bucket there (pnl: wallets under 10 closed trades; pnl_abs: wallets with no realized record at all), not a rung of the ladder. tier is the per-position ladder that /segments publishes as trade_size.

/segments remains the detailed catalogue (bounds, slugs, ranks, groupable); this is the flat taxonomy for a client that just needs the exact spellings.

The cohort catalogue: every bucket on every axis, with its boundaries.

Self-describing on purpose. A client that hard-codes bucket names learned from an absolute-$ ladder elsewhere will mis-map ours, which is a percentile ladder over realized PnL; this endpoint is how it finds that out.

Each row carries groupable: true for the three per-wallet ladders, false for trade_size, which is a per-position property and is not accepted as ?axis= by /heatmap or /segments/{cohort}/summary. Filter on it rather than assuming every published axis is a valid grouping key.

Aggregate positioning for one cohort at the latest snapshot.

perp_bias = (long - short) / equity and equity_exposure = (long + short) / equity, native perp account only: positions on the main dex over the native perp account value of the wallets holding them, each wallet counted once; builder-DEX positions are not included, and wallets without a known positive native equity are left out of perp_bias, equity_exposure and the numerator of equity_covered_share (main-dex notional of the counted wallets / main-dex notional of the whole cohort). Unbounded ratios (above 1 = more than 1x of equity), null when that equity <= 0. That equity is not total_equity, so perp_bias x total_equity is not total_long_usd - total_short_usd. Under openedWithin long/short are the qualifying positions and the equity the whole native account of every wallet holding one. exposure_ratio stays notional / margin used.

Coin x cohort positioning matrix — the whole board in one call.

The full cohort matrix for one coin — every bucket on an axis, hourly.

Data from 2026-04-07 (the first hour cohort labels are correct), on every axis: an older start is served from there (never a 400), paging stops there, and the envelope says data_from. Every row carries n_wallets, the wallets in the cohort holding the coin that hour.

/symbols/{symbol}/metrics returns one row per hour, either all cohorts summed or a single cohort. Rebuilding the matrix from it costs one request per cohort (12 for size, 13 for pnl); this returns all of them in one.

axis=tier is the PER-POSITION ladder — each position row's own notional bucket, DERIVED from the row's size_usd: the canonical ten dollar-range buckets, largest first, the website's spellings verbatim (>$2.5m, $1m-$2.5m, $500k-$1m, $250k-$500k, $100k-$250k, $50k-$100k, $25k-$50k, $10k-$25k, $1k-$10k, <$1k — /cohorts and /segments publish the ladder with bounds). Rows have the same shape as axis=size, the bucket in the cohort field. It is a grouping only here: this endpoint aggregates position rows, so each row sits in exactly one bucket, while the per-wallet endpoints (/heatmap, /segments/{cohort}/summary) keep rejecting it — a wallet straddles buckets. (The retired micro/small/medium/large/mega vocabulary is gone; sending one of those as a cohort filter anywhere returns a 400 naming this ladder.)

Paginated by HOUR, not by row — a row limit would cut a bucket in half and return an hour whose cohorts do not sum to its total. hours bounds the buckets; every cohort in a returned bucket comes with it.

No provisional row: this is bulk history, and a partial hour inside a matrix that will be differenced or z-scored produces a fake move at the right edge. Use /symbols/{symbol}/metrics for the current value.

include=volume,median_pnl adds two per-cohort columns to the rows of the newest bucket, volume_24h_usd and median_realized_pnl_usd (size and pnl only; see the parameter). They are computed at request time, so they describe the book now, not the bucket's hour.

⚠️ labelBasis matters for research. By default the pnl cohort is resolved from the dictionary AT QUERY TIME, so a historical row carries TODAY's grading — correct for "who is smart right now", lookahead for a backtest, because a wallet under the 10-closed-trade floor back then may be graded now. Pass labelBasis=point_in_time to get each row's label as it was that hour. Hours from 2026-08-07 on carry every field (unavailable_fields is empty). A window that reaches an earlier hour is served as one aggregate for all of its hours, and its position_count, position_count_long, total_unrealized_pnl, total_position_size and total_position_size_long are null (listed in unavailable_fields); so are those five fields under grading=unrealized and grading=realized-pit. Point-in-time matrices are stored aggregates and refuse openedWithin (400).

axis=size is always point-in-time (a stored column), axis=tier is always point-in-time (a pure function of the stored size_usd), axis=pnl_unrealized is always point-in-time (the HOURLY rollup stores it, see below) and axis=pnl_abs is always current (no frozen source exists); all four reject a conflicting labelBasis rather than silently ignoring it. Every row and the envelope carry label_basis so the answer is self-describing.

⚠️ grading selects WHICH PnL grading; label_computed says WHEN it was computed. The two are independent and the response carries both, on the envelope and on every row. A grading name is neutral by design — realized does not say whether the label is today's or the hour's — so the endpoint refuses to let the name travel alone.

* grading=realized (default on axis=pnl) — the percentile ladder over cumulative realized PnL. With the default labelBasis this is resolved at QUERY time, so every historical hour carries TODAY's grading: label_computed.lookahead is true and says so. With labelBasis=point_in_time it is the frozen ladder, and label_computed names the 2026-08-06 seam — before it the labels come from the 2026-08-17 point-in-time rebuild (daily resolution), from it they come from the row's own pnl_cohort_realized (hourly). Both halves are honest; a series crossing the seam changes label RESOLUTION, which a turnover count will read as a regime change that is an artefact. * grading=realized-pit — the same ladder graded point-in-time across the WHOLE window (day D on the cumulative as of the end of D-1), which is what makes it the control for a study crossing that seam. Rebuilt once a DAY: it is extended just after 00:00 UTC through 23:00 of the last complete UTC day, so a window reaching the present comes back 1 to 25 hours short rather than wrong. * grading=unrealized — "currently onside": hour H's rank over the wallet's last snapshot strictly before H. axis=pnl_unrealized is the legacy spelling of exactly this and keeps working; both reach one branch.

grading is refused on size, tier and pnl_abs, which rank no PnL, and realized-pit/unrealized refuse labelBasis=current rather than silently overriding it.

⚠️ freshness is how a REALTIME caller checks it is not trading a stale book. On any window that reaches the present the envelope carries {newest_ts, behind_hours, settled_lag_ceiling_hours, stale}. stale is the pre-computed verdict, so a consumer does not have to re-derive the rollup's cadence — the rollup writes hour H at H+1:00–H+1:30, so a bucket up to two hours old is healthy and the ceiling sits an hour above that.

It exists because prose was not enough. grading=realized-pit reads a table rebuilt once a DAY; ask it the way a poller does (?grading=realized-pit&hours=1, no start) and it returns its own newest bucket — identical in shape to a current one, and hours old. That gap is not a constant: the newest hour is 23:00 of the last complete UTC day, so it runs from 1 to 25 hours over each day and stale is true for most of it. Read the age off freshness.behind_hours rather than from any number written in prose.

For live trading use grading=realized with labelBasis=point_in_time: honest labels, and one hour behind the clock rather than up to a day.

A window that ends in the PAST gets no freshness — "the newest bar is four months old" answers a question a historical query did not ask, and would make every backtest fetch look broken.

axis=pnl_unrealized grades positioning, not skill. Each wallet is ranked by the unrealized PnL of its open positions as a share of account value — "currently onside" — over its last snapshot STRICTLY BEFORE hour H, and that rank labels hour H. The grading turns over ~44% of wallets per day (the realized ladder: ~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 a point-in-time pnl window that reaches before 2026-08-07, and a known three-day hole (2026-06-28..30, graded off days whose equity feed was down).

Data from 7 April 2026: the first hour cohort labels are correct. In the builder below, hours 1 replays the answer the showcase captured for that exact call. 720 hours is 30 days; hours goes up to 8,760 per request. end includes the hour it falls in (end=…T01:00:00Z returns the 01:00 hour): to stop after the last full hour HH, pass HH:59:59.

Hourly open-interest / position-count / bias series for one coin, optionally sliced to a single cohort.

Hourly by construction: the 5-minute snapshot table summed into hour buckets over-counts open interest ~12x, which is what forced the previous cohort aggregate to be rebuilt.

Every row carries provisional. It is True on at most one row — the newest, covering the hour still in progress — because the hourly rollup lands 60-120 minutes late and a "current positioning" read would otherwise be silently that stale. Its ts is a snapshot instant rather than an hour boundary and it changes on every poll; drop it when persisting a series. Present only on the first page of a window reaching the present.

With a cohort: data from 2026-04-07 (the first hour cohort labels are correct); an older start is served from there and the envelope says data_from. Without one (all cohorts combined) the series does not depend on any label and keeps its whole history.

Smart Money Index, Whale-vs-Shrimp Index, whale / smart bias: the website's numbers as RATIOS in [-1, +1] (the site multiplies by 100). latest is the newest 5-minute snapshot (its pnl rungs graded by today's PnL grading, latest.label_basis: current), series the settled hourly rows, newest first. smi = long share of the 3x smart / 2x smart / smart wallets minus long share of the rekt / 2x rekt / 3x rekt wallets; wsi = long share of the 4x whale .. whale wallets minus long share of the 2x shrimp / shrimp wallets; whale_bias and smart_bias (latest only) = (long - short) / (long + short) over those whale / smart wallets. A value is null, never 0, when a cohort holds no positions. series: data from 2026-04-07 (the first hour cohort labels are correct); an older start is served from there, and the envelope says data_from.

Positioning split by canonical position-size bucket for one coin.

Ten dollar-range buckets (largest first), derived from each row's size_usd — the same ladder, spellings and bounds as axis=tier on /symbols/{symbol}/cohort-metrics and the /cohorts catalogue. Empty buckets come back zero-filled so the table shape is stable.

The asset page's Whale Activity feed: a symbol's large fills, newest first. The feed keeps only the newest 200 fills over $50k per symbol of the last 24 hours, so on a busy symbol that is minutes, not a day: covered_from is how far back the answer reaches, truncated says that cap may have cut older fills inside the window, has_more that limit cut rows. Each row has ts, wallet, direction (buy | sell), size_token, size_usd, price, order_type (market = crossed the book, limit = rested), size_cohort (the wallet's size rung on its latest snapshot) and pnl_cohort (graded at the fill's own hour where that hour is labelled, else today; pnl_cohort_basis says which). Liquidations are not flagged.

One cohort's long / short / bias per hour, summed over every symbol. Ratios in [-1, +1]. A 404 names the axis only. axis=size groups positions by the size cohort stored on each position; axis=pnl by the realized-PnL cohort frozen at that hour (hourly from 2026-08-06, daily before it; see label_computed). Per hour: long_usd and short_usd in USD, bias = (long - short) / (long + short), null when both are 0, and position_count, which counts open positions ((wallet, symbol) pairs), not wallets. Newest first, settled hours only. include=leverage adds the three equity ratios described on that parameter. Data from 2026-04-07 (the first hour cohort labels are correct): an older start is served from there, and the envelope says data_from.

Stored events of one live-stream channel after a cursor, oldest first: the REST catch-up of wss://stream.vike.io/v1/stream/hl-cohorts, for what a client missed while it was disconnected (events are kept 3 days). Pass the channel's filters as query parameters, as on the socket: a list as a comma list (wallet=0x..,0x..), a number as a number (min_usd=1000); an unknown filter, or one the channel does not take, is a 400 naming it.

Channels and their filters:

- hl.cohort_bias: axis, cohort, coin - hl.cohort_flow: axis, cohort, coin - hl.cohort_leverage: axis, cohort - hl.indices: coin, index

Returns {events: [{cursor, event}], next_cursor, has_more}. event is exactly what the socket sent, so dedupe on event.event_id. Pass next_cursor back as cursor while has_more is true. A window in which the channel was idle (nobody subscribed) comes as an item {cursor, gap} in its place. A cursor older than the retention is a 410 naming the oldest cursor accepted; omit cursor to start there.

Without a cursor it starts 3 days minus 60 seconds back, the oldest cursor it still accepts; pass next_cursor back while has_more is true. Live, the same events arrive on the socket: WebSocket.