Contents

Price candles (OHLC)

Price candles (OHLC) of a Hyperliquid coin, oldest first.

GET/api/v1/candles/{coin}Every key

Description

Live buckets come from 30-second Hyperliquid mark samples (price: "mark", no volume); history before that from trade candles (Binance perpetual for coins listed there, else Hyperliquid) with volume (volumeUsd = quote volume where the venue reports it, volumeBase in Hyperliquid units, volumeVenue). Gaps stay gaps; complete: false marks a bucket with missing samples or the one still forming. from is clamped to the plan history, to to now minus the feed delay. Licence review: candles made only of Binance trades are left out (gaps) and mixed ones lose the Binance volume; coins without a Hyperliquid market answer 403 source_restricted (meta.restricted).

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 /candles/{coin}
Parameter	Description
`coin`string · pathrequired	Coin name, e.g. BTC or xyz:TSLA (case-insensitive).
`tf`string	Candle timeframe: 5m, 15m, 1h (default), 4h or 1d (UTC-aligned). 5m and 15m reach back 35 days (our 5-minute samples and 5-minute trade candles are kept that long, then hourly); older 5m / 15m buckets are gaps, so use 1h or coarser.one of 5m, 15m, 1h, 4h, 1d · default 1h
`from`string	Start (ISO 8601, optional; default: `limit` candles before `to`).ISO 8601, e.g. 2026-10-23T12:00:00Z
`to`string	End, exclusive (ISO 8601, optional; default now).ISO 8601, e.g. 2026-10-23T12:00:00Z
`limit`integer	Number of items, default 500, clamped to 1–5000.1–5000 · default 500
`fields`string	Comma-separated fields of every data.candles item to return, e.g. t,open,high,low,close (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 /candles/{coin}
Field	Description
`coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`tf`"5m" \| "15m" \| "1h" \| "4h" \| "1d"	Bucket interval (5m, 15m, 1h, …).
`candles[]`array of objects	Oldest → newest.
`candles[].t`string (ISO 8601)	Bucket start (UTC).
`candles[].open`number	Open price of the bucket.
`candles[].high`number	High price of the bucket.
`candles[].low`number	Low price of the bucket.
`candles[].close`number	Close price of the bucket.
`candles[].volumeUsd`number · nullable	Traded quote volume of the bucket where the venue reports it (USD).
`candles[].volumeBase`number · nullable	Traded volume in base units (Hyperliquid units).
`candles[].volumeVenue`"binance" \| "hyperliquid" · nullable	Venue the volume was traded on.
`candles[].price`"mark" \| "trades" \| "mixed"	mark = 30-second Hyperliquid mark samples, trades = trade candles of the volume venue, mixed = both within the bucket.
`candles[].complete`boolean	false when samples are missing in the bucket, it is still forming, or part of its OHLC is derived (rows from before high/low/open were stored; hourly rows compacted after 35 days, whose sample count is not kept).

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

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/candles/BTC?tf=1h&limit=48"

Example response

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

{
  "data": {
    "coin": "BTC",
    "tf": "1h",
    "candles": [
      {
        "t": "2026-10-27T11:00:00.000Z",
        "open": 79979,
        "high": 80129,
        "low": 79840,
        "close": 79893,
        "volumeUsd": null,
        "volumeBase": null,
        "volumeVenue": null,
        "price": "mark",
        "complete": true
      },
      {
        "t": "2026-10-27T12:00:00.000Z",
        "open": 79893,
        "high": 80474,
        "low": 79826,
        "close": 80340,
        "volumeUsd": null,
        "volumeBase": null,
        "volumeVenue": null,
        "price": "mark",
        "complete": true
      }
    ]
  },
  "meta": {
    "updatedAt": "2026-10-27T13:00: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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}

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

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.