Contents

Wallet detail

One tracked Hyperliquid wallet: stored account data, current positions (largest first), latest position events (increase / decrease kept 90 days, the other kinds 400 days) and totals.

GET/api/v1/wallets/{address}Every key

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 /wallets/{address}
Parameter	Description
`address`string · pathrequired	0x address (40 hex characters, any case).
`limit`integer	Number of position events, default 50, clamped to 1–200.1–200 · default 50

Response fields

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

Response fields of /wallets/{address}
Field	Description
`wallet`object	-
`wallet.address`string	Hyperliquid address, lowercase.
`wallet.label`string · nullable	Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified).
`wallet.accountValue`number · nullable	Account value (USD).
`wallet.pnlMonth`number · nullable	30-day PnL (leaderboard) (USD).
`wallet.vlmMonth`number · nullable	30-day volume (leaderboard) (USD).
`wallet.source`string · nullable	How the wallet was found (e.g. hl_leaderboard).
`wallet.priority`integer	Polling priority (1 = most often).
`wallet.firstSeen`string (ISO 8601)	First time this item was observed (ISO 8601 UTC).
`wallet.lastPolledAt`string (ISO 8601) · nullable	Last time the wallet was read from Hyperliquid (ISO 8601 UTC), null = not yet.
`wallet.positionCount`integer · nullable	Number of open positions.
`positions[]`array of objects	Current positions, largest first.
`positions[].address`string	Hyperliquid address (lowercase), or with venue "lighter" the Lighter account index.
`positions[].label`string · nullable	Wallet label (public label or leaderboard display name).
`positions[].accountValue`number · nullable	Account value (USD).
`positions[].coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`positions[].side`"long" \| "short"	Position side (for liquidations: the side of the liquidated position).
`positions[].size`number	Size in coins.
`positions[].entryPx`number · nullable	Entry price.
`positions[].positionUsd`number	Notional (USD).
`positions[].leverage`number · nullable	Leverage of the position (notional / margin).
`positions[].leverageType`string · nullable	cross \| isolated
`positions[].liqPx`number · nullable	Liquidation price.
`positions[].liqDistance`number · nullable	Signed distance from the mark to the liquidation price, fraction (−0.12 = 12 % below the mark).
`positions[].mark`number · nullable	Hyperliquid mark price.
`positions[].marginUsed`number · nullable	Margin used (USD).
`positions[].unrealizedPnl`number · nullable	Unrealised PnL (USD).
`positions[].updatedAt`string (ISO 8601)	Newest data time of this item (ISO 8601 UTC).
`positions[].venue`"hyperliquid" \| "lighter"	Venue of the position (present for Lighter rows; absent = Hyperliquid).
`events[]`array of objects	Latest position events, newest first.
`events[].id`integer	Stable id of the item; on paginated feeds the order key together with ts.
`events[].ts`string (ISO 8601)	Time of the event (ISO 8601 UTC).
`events[].address`string	Hyperliquid address, lowercase.
`events[].label`string · nullable	Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified).
`events[].coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`events[].kind`"open" \| "close" \| "increase" \| "decrease" \| "flip" \| "liquidated"	Kind of whale position change (liquidated = confirmed by the wallet’s Hyperliquid liquidation fills).
`events[].side`"long" \| "short" · nullable	Position side (long / short); for trades and orders the side named in the description.
`events[].sizeDelta`number · nullable	Change in coins.
`events[].usdDelta`number · nullable	Change (USD).
`events[].price`number · nullable	Price in the quote currency of the venue (USD / USDT / USDC).
`events[].data`any	Kind-specific details (JSON) or null.
`totals`object	Sums over the rows of this object.
`totals.positionUsd`number	Open notional (USD).
`totals.longUsd`number	Long notional (USD).
`totals.shortUsd`number	Short notional (USD).
`totals.unrealizedPnl`number	Unrealised PnL summed over the positions that report one (USD).
`totals.unrealizedPnlMissing`integer	Positions without a reported unrealised PnL (left out of unrealizedPnl, not counted as 0).

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/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060"

Example response

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

{
  "data": {
    "wallet": {
      "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
      "label": null,
      "accountValue": 141229571.24,
      "pnlMonth": 122795733.29,
      "vlmMonth": 217999124.81,
      "source": "hl_leaderboard",
      "priority": 1,
      "firstSeen": "2026-10-22T23:36:37.976Z",
      "lastPolledAt": "2026-10-27T13:10:10.972Z",
      "positionCount": 25
    },
    "positions": [
      {
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "accountValue": 141229571.24,
        "coin": "ETH",
        "side": "short",
        "size": 106412.8112,
        "entryPx": 2322.74,
        "positionUsd": 247633252.94,
        "leverage": 5,
        "leverageType": "cross",
        "liqPx": 3743.37777395,
        "liqDistance": 0.607089617,
        "mark": 2329.29,
        "marginUsed": 49526650.59,
        "unrealizedPnl": -463798.42,
        "updatedAt": "2026-10-27T13:10:10.972Z"
      },
      {
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "accountValue": 141229571.24,
        "coin": "BTC",
        "side": "short",
        "size": 2613.28915,
        "entryPx": 76343.5,
        "positionUsd": 209447285.51,
        "leverage": 5,
        "leverageType": "cross",
        "liqPx": 138286.523033,
        "liqDistance": 0.7239914108,
        "mark": 80213,
        "marginUsed": 41889457.1,
        "unrealizedPnl": -9939592.53,
        "updatedAt": "2026-10-27T13:10:10.972Z"
      }
    ],
    "events": [
      {
        "id": 223009,
        "ts": "2026-10-27T12:36:43.304Z",
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "coin": "PUMP",
        "kind": "decrease",
        "side": "short",
        "sizeDelta": -2601910,
        "usdDelta": -10972.25,
        "price": 0.004217,
        "data": {
          "prevSize": 1623693116,
          "newSize": 1621091206,
          "prevSide": "short",
          "entryPx": 0.004608,
          "liqPx": 0.0917287092,
          "leverage": 5,
          "leverageType": "cross",
          "prevUnrealizedPnl": 632546.946695,
          "prevPolledAt": "2026-10-27T12:34:08.753Z",
          "polledAt": "2026-10-27T12:36:43.304Z",
          "positionUsd": 6836141.62,
          "prevPositionUsd": 6847113.87
        }
      },
      {
        "id": 222693,
        "ts": "2026-10-27T12:31:34.296Z",
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "coin": "PUMP",
        "kind": "decrease",
        "side": "short",
        "sizeDelta": -2851153,
        "usdDelta": -11977.69,
        "price": 0.004201,
        "data": {
          "prevSize": 1626781839,
          "newSize": 1623930686,
          "prevSide": "short",
          "entryPx": 0.004608,
          "liqPx": 0.0918533171,
          "leverage": 5,
          "leverageType": "cross",
          "prevUnrealizedPnl": 650018.048084,
          "prevPolledAt": "2026-10-27T12:29:00.988Z",
          "polledAt": "2026-10-27T12:31:34.296Z",
          "positionUsd": 6822132.81,
          "prevPositionUsd": 6834110.51
        }
      }
    ],
    "totals": {
      "positionUsd": 707092087.02,
      "longUsd": 250824.09,
      "shortUsd": 706841262.94,
      "unrealizedPnl": 3036457.49,
      "unrealizedPnlMissing": 0
    }
  },
  "meta": {
    "updatedAt": "2026-10-27T13:10:10.972Z",
    "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 wallet() / wallet()

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.

Wallet detail

Description

Who can call it

Parameters

Response fields

Errors