Contents

Long/short positioning

Long/short positioning per coin: Hyperliquid from the tracked positions (USD and wallet counts per side, ratio = longUsd / shortUsd) and the public account ratios of the enabled exchanges (Binance: all accounts, top accounts, top positions; Bybit; OKX) from the last 60 minutes.

GET/api/v1/long-shortEvery key

Description

A switched-off exchange is left out of the row (no key); null means the exchange is on but has no ratio for the coin. Sorted by Hyperliquid open interest. Licence review: the exchanges’ published ratios are their data 1:1 and left out like a switched-off exchange (meta.restricted); rows then cover coins with a Hyperliquid market.

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 /long-short
Parameter	Description
`coin`string	Only this coin (optional).
`limit`integer	Number of items, default 50, clamped to 1–500.1–500 · default 50
`fields`string	Comma-separated fields of every item to return, e.g. coin,hl (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field.
`format`string	json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON.one of json, csv, ndjson · default json

Response fields

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

Response fields of /long-short
Field	Description
`[].coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`[].hl`object · nullable	Hyperliquid from the tracked positions; null when no tracked position exists.
`[].hl.longUsd`number	Tracked long notional (USD).
`[].hl.shortUsd`number	Tracked short notional (USD).
`[].hl.longAccounts`integer	Tracked wallets with a long position.
`[].hl.shortAccounts`integer	Tracked wallets with a short position.
`[].hl.ratio`number · nullable	longUsd / shortUsd.
`[].updatedAt`string (ISO 8601) · nullable	Newest data time of this item (ISO 8601 UTC).
`[].binance`object · nullable	Binance published long/short ratios (only while Binance is switched on and licensed for the API).
`[].binance.accountRatio`number · nullable	Long / short accounts.
`[].binance.topAccountRatio`number · nullable	Top traders, accounts.
`[].binance.topPositionRatio`number · nullable	Top traders, positions.
`[].bybit`object · nullable	Bybit published long/short ratio (only while Bybit is switched on and licensed for the API).
`[].bybit.accountRatio`number · nullable	Long / short accounts.
`[].okx`object · nullable	OKX published long/short ratio (only while OKX is switched on and licensed for the API).
`[].okx.accountRatio`number · nullable	Long / short accounts.

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

Long/short ratio (venue variants) (how it is computed and its limits)

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/long-short?limit=20"

Example response

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

{
  "data": [
    {
      "coin": "BTC",
      "hl": {
        "longUsd": 1543688921.02,
        "shortUsd": 1593635392.17,
        "longAccounts": 2351,
        "shortAccounts": 1254,
        "ratio": 0.9686587839
      },
      "updatedAt": "2026-10-27T13:12:18.157Z"
    },
    {
      "coin": "ETH",
      "hl": {
        "longUsd": 1241116739.56,
        "shortUsd": 1262161538.81,
        "longAccounts": 1241,
        "shortAccounts": 825,
        "ratio": 0.9833263821
      },
      "updatedAt": "2026-10-27T13:12:18.393Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:12:18.393Z",
    "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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}

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

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.