HL Cohorts REST

10 operations, every one a GET, all under https://data.vike.io/v1/hl-cohorts/. HL Cohorts is Hyperliquid positioning grouped by cohort. Every wallet sits on ladders — its account size, the percentile of its realized PnL, the same PnL in dollar bands — and these routes answer how each rung is positioned: at the latest snapshot, hour by hour, per symbol or across the whole book.

Every path in this namespace is written relative to https://data.vike.io/v1/hl-cohorts. The fenced line at the top of each endpoint's page carries the full path.

Start here

What it looks like in use

# orient: the exact labels of every ladder, the strings ?cohort= accepts
curl -s "https://data.vike.io/v1/hl-cohorts/cohorts" \
  -H "X-API-KEY: $VIKE_API_KEY"

# now: how the largest accounts are positioned at the latest snapshot
curl -s "https://data.vike.io/v1/hl-cohorts/segments/4x_whale/summary?axis=size" \
  -H "X-API-KEY: $VIKE_API_KEY"

# history: the same cohort across the whole book, hourly, for the last week
curl -s "https://data.vike.io/v1/hl-cohorts/segments/4x_whale/history?axis=size" \
  -H "X-API-KEY: $VIKE_API_KEY"

# one symbol: every size cohort on BTC, hourly, in one call
curl -s "https://data.vike.io/v1/hl-cohorts/symbols/BTC/cohort-metrics?axis=size&hours=24" \
  -H "X-API-KEY: $VIKE_API_KEY"

Before you call anything

Auth. The same key and the same shared hourly counter as every other namespace — see Authentication and Rate limits.

Errors. Input the service rejected is a 400 (an unknown cohort on /segments/{cohort}/history is a 404), an upstream data failure is a 503, and a rate-limit trip is a 429. A failure is never reported as a 200 with an empty body. See Errors.

Paging. /symbols/{symbol}/metrics and /symbols/{symbol}/cohort-metrics return nextCursor — pass it back verbatim. /segments/{cohort}/history and /symbols/{symbol}/indices page back by end and say has_more. /symbols/{symbol}/large-fills has no paging: its view holds at most 200 fills per symbol.

The ladders and the labels

axis picks the ladder and cohort one rung on it: size (account value), pnl (percentile of cumulative realized PnL), pnl_abs (the same PnL in dollar bands) and the per-position tier. Cohorts and axes defines them and says which axes can group.

A cohort label is a fact about a wallet at one moment, so the routes that return history say which moment their labels come from (label_basis, and label_computed where a PnL grading is involved). /symbols/{symbol}/cohort-metrics with labelBasis=point_in_time serves each hour's label as it stood that hour, which is what a backtest needs; Label basis has the rules.

Ladders

One cohort

The board

Symbols

{symbol} is an HL ticker such as BTC.

How this differs from the Hyperliquid namespace

/v1/hyperliquid is wallet- and market-level: one wallet's history, positions, leaderboards, liquidations, builders, candles and the file archive. A cohort there is a filter — /positions, /leaderboard and /liquidations/risk take axis and cohort to narrow their rows, and /wallets/{address} reports one wallet's labels. Here the cohort is the unit the answer is grouped by.

Seven of these routes used to be documented under /v1/hyperliquid/. All ten still answer at /v1/hyperliquid/<path>, served by the same handler with the same parameters and the same body, but only the /v1/hl-cohorts/ paths are in the OpenAPI document. The older /v1/hyperliquid/coins/{symbol}/... spellings of three of them have no /v1/hl-cohorts/ twin.

Related

• Cohorts and axes and Label basis — the ladders, and when a label was computed.
• Hyperliquid MCP tools — hl_segments, hl_cohort_metrics and hl_market serve these routes as tools, calling the same query functions.
• Backtest cohort positioning without lookahead — the point-in-time matrix joined to candles.
• Rate limits — the shared hourly counter these calls spend.
• Errors — the status codes and the error envelope.