Hyperliquid Segments
hl_segmentsThe Hyperliquid cohort vocabulary and its latest-snapshot positioning, by view. cohorts: the label sets per ladder, the exact spellings every cohort parameter accepts. segments: the catalogue with bounds, ranks and what each ladder measures (size is account value in USD; pnl is a percentile rank of cumulative realized PnL, not dollars; pnl_abs is dollars). summary: everything ONE cohort holds right now across all symbols: long/short notional in USD, bias a fraction from -1 to +1, pct_wallets_in_profit a FRACTION from 0 to 1 despite its name, exposure_ratio = notional / margin used, 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 (each wallet once, the whole account even under opened_within); builder-DEX positions are not included; wallets without a known positive native equity are left out of perp_bias, equity_exposure and this share's numerator, see equity_covered_share (main-dex notional of the counted wallets / of the whole cohort). Unbounded ratios (above 1 = over 1x; null when equity <= 0); that equity is not total_equity, so perp_bias x total_equity != total_long_usd - total_short_usd. heatmap: the whole symbol x cohort board (large: every symbol with open interest; empty cells are omitted). Positions are the latest 5-minute snapshot. history: ONE cohort (cohort + axis, both required; axis is size or pnl only) hour by hour, summed over all symbols, newest first, from 2026-04-07: long_usd and short_usd in USD, bias = (long - short) / (long + short), a RATIO from -1 to +1 (null when both are 0), position_count = open positions, NOT wallets. Each hour carries the cohort label it had then (label_basis is point_in_time; pnl labels are daily before 2026-08-06, see label_computed). hours sizes the window, limit caps the rows, has_more says older rows exist. With include=leverage each hour also carries perp_bias, equity_exposure and equity_covered_share, the three summary ratios of that hour (null before 2026-08-11 and for a missing hour; perp_bias and equity_exposure are also null where no wallet has a known positive equity, and equity_covered_share is 0 when none is counted). An unknown cohort for the axis is an error. Same data as GET /v1/hl-cohorts/{cohorts, segments, segments/{cohort}/summary, heatmap, segments/{cohort}/history}.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "hl_segments"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ISO-8601 UTC upper bound, e.g. 2026-10-02T00:00:00Z. `history` only: with no `start`, the window is the `hours` newest hours at or before it. Used by view: history. | |
| axis | No | Cohort ladder: `size` = account-value tiers in USD, `pnl` = percentile rank of cumulative realized PnL (NOT dollars), `pnl_abs` = dollar bands of that same PnL. Per-position `trade_size` / `tier` is refused here. `history` serves history for `size` and `pnl` only, and requires `axis`. Default by view: summary size, heatmap size. Used by view: summary, heatmap, history. Required by view: history. | |
| view | No | What to read. `segments`: the catalogue of every cohort bucket with its bounds and what the ladder measures. `cohorts`: the flat label sets, i.e. the exact spellings every `cohort` parameter accepts. `summary`: what ONE cohort holds right now across all symbols. `heatmap`: the whole symbol x cohort board at the latest snapshot. `history`: ONE cohort's hourly long, short and bias summed over all symbols, newest first (axis size or pnl only). Default `segments`. | segments |
| hours | No | `history` only: window length in hours when `start` is omitted, ending at `end` or now. Max 8760. Used by view: history. | |
| limit | No | `history` only: max hourly rows, newest first; `has_more` says older ones exist, page back with `end` = the oldest `ts` minus 1 second. Max 5000. Used by view: history. | |
| start | No | ISO-8601 UTC lower bound, e.g. 2026-10-01T00:00:00Z. `history` only; hours before 2026-04-07 are never returned. Used by view: history. | |
| cohort | No | One label on `axis`, spelled exactly as `hl_segments` view=cohorts lists it, e.g. `whale` (size) or `3x smart` (pnl). Used by view: summary, history. Required by view: summary, history. | |
| include | No | `history` only: comma list, only `leverage`; default none (nothing extra is read). Adds to every hourly row `perp_bias` = (long - short) / equity, `equity_exposure` = (long + short) / equity and `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), native perp account only (main-dex positions of wallets with a known positive native equity, each wallet once; builder-DEX positions are not included). An hour with no stored row, and any hour before `leverage.data_from` (2026-08-11), is null on all three (never 0). `perp_bias` and `equity_exposure` are also null when no counted wallet has a positive equity; `equity_covered_share` is null when the cohort holds no main-dex notional and a real 0 when it holds some but no wallet is counted. Hours rebuilt from fills rather than read from snapshots are null. An unknown token is refused. Used by view: history. | |
| opened_within | No | Only positions opened within this window: `24h`, `7d`, `30d` or `all`; positions with no known open time are left out of every bounded window. Used by view: summary, heatmap. | all |