Contents

Cohort positioning

Positioning of tracked Hyperliquid wallets by cohort: size (shrimp < $10K, fish, dolphin, shark, whale ≥ $10M account value) and all-time PnL (top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M): long / short notional, wallets and long share now, its change over 15m / 1h / 4h / 24h / 3d / 7d (from 5-min snapshots, capped at the plan history), recent position changes with cohorts and the net flow of the last hour.

GET/api/v1/cohortsEvery key

Description

Coverage is the wallets this service polls (large wallets far better than small ones).

Who can call it

Available with every key and keyless (X-Blockmetric-Access: public). Keys of Free accounts get free-tier data (real-time feeds, 30 days of history, heatmap over time for every coin over the last 24 hours, liquidation levels now for every coin, the same as the free web plan); Pro and Desk keys the data of their plan; API Dev / API Pro raise the limits.

No key: 24 h
Free: 30 days
Pro: 365 days
Desk: 1095 days
API Dev: 365 days
API Pro: 1095 days

History window per plan. Limits: Authentication & limits.

Parameters

Parameters of /cohorts
Parameter	Description
`coin`string	Coin, or ALL (default) for every position.
`dim`string	size \| pnl. With `cohort`: only changes of that cohort.one of size, pnl
`cohort`string	shrimp \| fish \| dolphin \| shark \| whale \| top \| profitable \| flat \| losing \| rekt (needs dim).one of shrimp, fish, dolphin, shark, whale, top, profitable, flat, losing, rekt
`limit`integer	Number of items, default 30, clamped to 1–200.1–200 · default 30

Response fields

Every success is { data, meta }; these are the fields of data. meta is the same on every endpoint.

Response fields of /cohorts
Field	Description
`coin`string	Coin or ALL.
`snapshotAt`string (ISO 8601) · nullable	Newest 5-min snapshot.
`rows[]`array of objects	The rows of this view.
`rows[].dim`"size" \| "pnl"	Cohort dimension: size (account value) or pnl (all-time PnL).
`rows[].cohort`string	Cohort key within its dimension.
`rows[].label`string	Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified).
`rows[].longUsd`number	Long notional (USD).
`rows[].shortUsd`number	Short notional (USD).
`rows[].longWallets`integer	Wallets on the long side.
`rows[].shortWallets`integer	Wallets on the short side.
`rows[].longShare`number · nullable	longUsd / (longUsd + shortUsd).
`rows[].change`object	Change of longShare against the snapshot that long ago (fraction points); windows beyond the plan history are missing.
`rows[].change.15m`number · nullable	Change over 15 minutes.
`rows[].change.1h`number · nullable	Change over 1 hour.
`rows[].change.4h`number · nullable	Change over 4 hours.
`rows[].change.24h`number · nullable	Change over 24 hours.
`rows[].change.3d`number · nullable	Change over 3 days.
`rows[].change.7d`number · nullable	Change over 7 days.
`since`string (ISO 8601) · nullable	Oldest snapshot.
`changes[]`array of objects	Recent position changes ≥ $50k with cohorts (delayed for free keys).
`changes[].id`integer	Stable id of the item; on paginated feeds the order key together with ts.
`changes[].ts`string (ISO 8601)	Time of the event (ISO 8601 UTC).
`changes[].address`string	Hyperliquid address, lowercase.
`changes[].coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`changes[].kind`"open" \| "close" \| "increase" \| "decrease" \| "flip" \| "liquidated"	Kind of the item (enum of this field).
`changes[].side`"long" \| "short" · nullable	Position side (for liquidations: the side of the liquidated position).
`changes[].usdDelta`number	Signed USD change.
`changes[].price`number · nullable	Price in the quote currency of the venue (USD / USDT / USDC).
`changes[].sizeCohort`"shrimp" \| "fish" \| "dolphin" \| "shark" \| "whale" · nullable	Size cohort by account value: shrimp < $10K, fish, dolphin, shark, whale ≥ $10M.
`changes[].pnlCohort`"top" \| "profitable" \| "flat" \| "losing" \| "rekt" · nullable	PnL cohort by all-time PnL: top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M.
`netFlow1h[]`array of objects	Net notional added per cohort and side in the last hour.
`netFlow1h[].dim`"size" \| "pnl"	Cohort dimension: size (account value) or pnl (all-time PnL).
`netFlow1h[].cohort`string	Cohort key within its dimension.
`netFlow1h[].longUsd`number	Long notional in USD.
`netFlow1h[].shortUsd`number	Short notional in USD.
`netFlow1h[].events`integer	Events of this view (newest first) or their count.
`maxMinutes`integer	Longest trend window of the plan.

Errors

400invalid_param Invalid parameter
401unauthorized Missing or invalid API key
403plan_required Plan does not include this
403scope_required Key not scoped for this API
403ip_not_allowed Address not on the IP allowlist of the key
403origin_not_allowed Key used from a browser origin it does not allow
403source_restricted Exchange data not redistributed
403https_required https required
429rate_limited Per-minute limit reachedretry
429daily_limit_exceeded Daily limit reachedretry
429stream_limit Too many open streamsretry
500internal_error Internal errorretry

Methodology

Wallet cohorts (how it is computed and its limits)

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/cohorts?coin=BTC"

Example response

HTTP 200Real data from 2026-10-27 13:10 UTC

{
  "data": {
    "coin": "BTC",
    "snapshotAt": "2026-10-27T13:10:00.000Z",
    "rows": [
      {
        "dim": "size",
        "cohort": "whale",
        "label": "Whale (≥ $10M)",
        "longUsd": 311625613.68,
        "shortUsd": 868589539.66,
        "longWallets": 7,
        "shortWallets": 17,
        "longShare": 0.2640413596,
        "change": {
          "15m": 0.0017261481,
          "1h": 0.0073477515,
          "4h": 0.0049861231,
          "24h": 0.0456011833,
          "3d": 0.0700297538,
          "7d": null
        }
      },
      {
        "dim": "size",
        "cohort": "shark",
        "label": "Shark ($1M–10M)",
        "longUsd": 585266663.15,
        "shortUsd": 347128405,
        "longWallets": 76,
        "shortWallets": 84,
        "longShare": 0.6277024441,
        "change": {
          "15m": -0.0029585558,
          "1h": 0.0166798925,
          "4h": 0.0181038648,
          "24h": -0.0044729906,
          "3d": -0.0514425533,
          "7d": null
        }
      }
    ],
    "since": "2026-10-23T05:50:00.000Z",
    "changes": [
      {
        "id": 225031,
        "ts": "2026-10-27T13:11:48.816Z",
        "address": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
        "coin": "BTC",
        "kind": "increase",
        "side": "long",
        "usdDelta": 194429.59,
        "price": 80196,
        "sizeCohort": "whale",
        "pnlCohort": "top"
      },
      {
        "id": 224982,
        "ts": "2026-10-27T13:11:18.226Z",
        "address": "0x8730154f2c794a59cd6adb0d8328a9770c13b616",
        "coin": "BTC",
        "kind": "close",
        "side": "long",
        "usdDelta": -160392,
        "price": 80196,
        "sizeCohort": "shrimp",
        "pnlCohort": "flat"
      }
    ],
    "netFlow1h": [
      {
        "dim": "size",
        "cohort": "shark",
        "longUsd": 32902179.05,
        "shortUsd": -2872109.46,
        "events": 213
      },
      {
        "dim": "pnl",
        "cohort": "top",
        "longUsd": 29028790.11,
        "shortUsd": 1575474.44,
        "events": 110
      }
    ],
    "maxMinutes": 525600
  },
  "meta": {
    "updatedAt": "2026-10-27T13:10:00.000Z",
    "source": "hyperliquid",
    "sources": [
      "hyperliquid"
    ],
    "plan": "api_dev",
    "delayMinutes": 0,
    "commercial": false,
    "license": {
      "id": "internal",
      "display": false,
      "attributionRequired": false,
      "attribution": null,
      "redistribution": false,
      "mauCap": null,
      "terms": "https://blockmetric.io/terms#api-license"
    },
    "attribution": {
      "text": "Data by Blockmetric · Source: Blockmetric Research",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 365,
      "historyFrom": "2025-10-27T13:14:00.000Z"
    }
  }
}

More options: open in the explorer · SDK method cohorts() / cohorts()

Code snippets in these docs are licensed under MIT-0: copy them into your own code without attribution. The SDKs, CLI and MCP server will be, once published, Apache-2.0; the name Blockmetric is not licensed (forks must be renamed). Data from the API is governed by the API terms; third-party exchange data by the exchange’s terms.