Contents

Open interest added per price band

Where open interest was added and removed on the exchanges (Binance, Bybit; OKX while enabled), per price band: the "open interest added at this price" layer of the heatmap.

GET/api/v1/heatmap/{coin}/open-interestEvery key

Description

Built only from what the exchanges publish and our collector stores every minute (open interest and the exchange's own mark price, kept in 5-minute buckets for 35 days): for two consecutive 5-minute buckets of one exchange, the change of open interest in contracts, valued at the bucket's price (the middle of its high and low), goes into the price band of that price. addedUsd = the positive changes, removedUsd = the negative ones, netUsd = added minus removed, steps = 5-minute steps with a change. No leverage is assumed and no liquidation price is estimated: this is not a position map. Limits: only the net change per 5 minutes is visible (openings and closings inside one step offset each other); a new contract always has a long and a short side, so added open interest does not say who bought; a step whose price range crosses a band edge counts in the band of its middle price (spanningSteps); a gap in our collection is never bridged; Binance open interest of coins outside the top 60 is read in rotation, so a change can land a few minutes late. Licence review: venue=binance / bybit answers 403 source_restricted; venue=all (default) publishes the sum over the exchanges per band where at least two withheld exchanges contributed to it (otherwise the band keeps its steps and venues and has null amounts, withheld: true), byVenue lists only exchanges that are not withheld, and totals add up the published bands. Same coins per plan as /heatmap/{coin} (free key: BTC, ETH and HYPE).

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 /heatmap/{coin}/open-interest
Parameter	Description
`coin`string · pathrequired	Coin name as on Hyperliquid, e.g. BTC (case-insensitive). Exchange listings are matched to it (kPEPE = 1000PEPE).
`hours`integer	Window in hours, default 24, clamped to 1 to 840 (35 days of 5-minute open interest) and to the plan's heatmap history (free key and keyless the last 24 hours, Pro / API Dev 1 year, Desk / API Pro 3 years; meta.warnings says so).1–840 · default 24
`end`string	End of the window (ISO 8601, default now), rounded up to the end of its 5-minute step (from / to say which steps were read). Clamped to now and to the readable history.ISO 8601, e.g. 2026-10-23T12:00:00Z
`venue`string	all (default: every enabled exchange, summed per band) \| binance \| bybit \| okx (one exchange; 403 source_restricted while its licence review is pending, 400 when switched off).one of all, binance, bybit, okx · default all
`bandPct`number	Band width in percent of the price, default 0.5 (a round step near it, like the heatmap rows), 0.1 to 5.0.1–5 · default 0.5

Response fields

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

Response fields of /heatmap/{coin}/open-interest
Field	Description
`coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`venue`"all" \| "binance" \| "bybit" \| "okx"	The venue asked for (all = every enabled exchange, summed per band).
`venues[]`array of "binance" \| "bybit" \| "okx"	Exchanges read for this answer (enabled ones).
`from`string (ISO 8601)	Window start.
`to`string (ISO 8601)	Window end.
`hours`integer	Window in hours.
`mark`number · nullable	Hyperliquid mark now (the band width is a round step near bandFraction of it).
`bandSize`number	Width of a price band (USD); 0 without a price.
`bandFraction`number	Band width asked for, fraction of the price (0.005 = 0.5 %).
`stepMinutes`integer	Length of one step: two consecutive 5-minute buckets of our collection.
`steps`integer	Steps with a change of open interest in the window (all exchanges read).
`spanningSteps`integer	Of those, steps whose price range crossed a band edge (counted in the band of their middle price).
`firstStep`string (ISO 8601) · nullable	First step with data in the window.
`lastStep`string (ISO 8601) · nullable	Last step with data in the window.
`fullResolutionDays`integer	Days of 5-minute open interest kept (older history is hourly and not used).
`totals`object	Sums over the rows of this object.
`totals.addedUsd`number	Open interest added over the published bands (USD).
`totals.removedUsd`number	Open interest removed over the published bands (USD).
`totals.netUsd`number	addedUsd minus removedUsd (USD).
`totals.withheldBands`integer	Bands without amounts (licence review: a single withheld exchange would be readable from them).
`bands[]`array of objects	Price bands with a change, lowest first.
`bands[].priceLo`number	Lower edge of the band (USD, inclusive).
`bands[].priceHi`number	Upper edge of the band (USD, exclusive).
`bands[].addedUsd`number · nullable	Open interest added while the price was in this band: the sum of the positive 5-minute changes, in contracts valued at the step price; null = withheld (USD).
`bands[].removedUsd`number · nullable	Open interest removed while the price was in this band (sum of the negative changes, as a positive number); null = withheld (USD).
`bands[].netUsd`number · nullable	addedUsd minus removedUsd; null = withheld (USD).
`bands[].steps`integer	5-minute steps with a change whose price was in this band.
`bands[].venues[]`array of "binance" \| "bybit" \| "okx"	Exchanges with a change in this band.
`bands[].byVenue`object	Per exchange (only exchanges that are not withheld by the licence review).
`bands[].byVenue.binance`object	The part of binance in this band.
`bands[].byVenue.bybit`object	The part of bybit in this band.
`bands[].byVenue.okx`object	The part of okx in this band.
`bands[].withheld`boolean	true: amounts left out: with the licence review pending, the sum over the exchanges of this band would be one exchange's own figure.

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
404not_found Not found
429rate_limited Per-minute limit reachedretry
429daily_limit_exceeded Daily limit reachedretry
429stream_limit Too many open streamsretry
500internal_error Internal errorretry

Methodology

Open interest (how it is computed and its limits)

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/heatmap/BTC/open-interest?hours=24"

Example response

HTTP 200Real data from 2026-11-03 19:55 UTC

{
  "data": {
    "coin": "BTC",
    "venue": "all",
    "venues": [
      "binance",
      "bybit"
    ],
    "from": "2026-11-02T20:00:00.000Z",
    "to": "2026-11-03T20:00:00.000Z",
    "hours": 24,
    "mark": 77584,
    "bandSize": 500,
    "bandFraction": 0.005,
    "stepMinutes": 5,
    "steps": 556,
    "spanningSteps": 80,
    "firstStep": "2026-11-02T20:00:00.000Z",
    "lastStep": "2026-11-03T19:55:00.000Z",
    "fullResolutionDays": 35,
    "totals": {
      "addedUsd": 852929180.26,
      "removedUsd": 726740142.79,
      "netUsd": 126189037.47,
      "withheldBands": 0
    },
    "bands": [
      {
        "priceLo": 76000,
        "priceHi": 76500,
        "addedUsd": 72099857.89,
        "removedUsd": 24668365.61,
        "netUsd": 47431492.28,
        "steps": 37,
        "venues": [
          "binance",
          "bybit"
        ]
      },
      {
        "priceLo": 76500,
        "priceHi": 77000,
        "addedUsd": 460855501.39,
        "removedUsd": 300436948.97,
        "netUsd": 160418552.42,
        "steps": 301,
        "venues": [
          "binance",
          "bybit"
        ]
      }
    ]
  },
  "meta": {
    "updatedAt": "2026-11-03T19:55:00.000Z",
    "source": "binance,bybit",
    "sources": [
      "binance",
      "bybit"
    ],
    "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: Binance · Bybit",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 365,
      "historyFrom": "2025-11-03T20:00:00.000Z"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}

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

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.