Contents

Whale movements (on-chain + Hyperliquid)

Whale movements, newest first, in one feed: large on-chain transfers (Ethereum, Arbitrum, Base from $1M, stablecoins from $5M; Bitcoin from $1M, change excluded), exchange in- and outflows (exchanges’ own proof-of-reserves addresses), stablecoin mints / burns, bridge transfers, large swaps on the biggest Uniswap v3 / Aerodrome pools (from $500K) and Hyperliquid whale position changes and large Hyperliquid trades (from $1M).

GET/api/v1/movementsEvery keyPaginated

Description

Labels only from cited sources; every other wallet is named by its address. USD: stablecoins at their latest fresh Chainlink answer (USDT, USDC, DAI / USD), WBTC at the Hyperliquid BTC mark × Chainlink WBTC / BTC, other assets at the Hyperliquid mark; no fresh price → usd null and priceSource "unavailable" (such items never pass minUsd). priceSource and details.value say which. CEX trade prints are not included.

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 /movements
Parameter	Description
`type`string	Comma list of transfer \| exchange_in \| exchange_out \| exchange_exchange \| mint \| burn \| bridge \| dex_buy \| dex_sell \| perp_position \| big_trade (optional, default all).
`chain`string	ethereum \| arbitrum \| base \| bitcoin \| hyperliquid (optional).one of ethereum, arbitrum, base, bitcoin, hyperliquid
`asset`string	Asset symbol, e.g. BTC, ETH, USDT, USDC (ETH also finds WETH, BTC finds WBTC, USDT finds USDT0) (optional).
`minUsd`number	Minimum value in USD on top of the feed thresholds, default 0.≥ 0 · default 0
`labelled`boolean	true = only items with a labelled sender or receiver.one of true, false · default false
`address`string	Only movements of this EVM or Bitcoin address (includes smaller transfers of addresses watched by alert rules).
`since`string	ISO time; clamped to the plan history.ISO 8601, e.g. 2026-10-23T12:00:00Z
`limit`integer	Number of items, default 50, clamped to 1–500.1–500 · default 50
`cursor`string	Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history.
`fields`string	Comma-separated fields of every item to return, e.g. ts,type,asset,usd,from,to (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 /movements
Field	Description
`[].id`string	"m<id>" on-chain movement, "p<id>" Hyperliquid position change, "t<id>" Hyperliquid trade print.
`[].ts`string (ISO 8601)	Block time (on-chain) or event time.
`[].type`string (enum)	Type of the item (enum of this field).
`[].chain`string	ethereum \| arbitrum \| base \| bitcoin \| hyperliquid.
`[].asset`string	Asset symbol (USDT, USDC, ETH, WETH, BTC, WBTC, …) or Hyperliquid coin.
`[].amount`number · nullable	Units of the asset.
`[].usd`number · nullable	Value at our price: stablecoins at the fresh Chainlink answer, WBTC at Hyperliquid BTC mark × Chainlink WBTC / BTC, other assets at the Hyperliquid mark; null = price unavailable (USD).
`[].priceSource`string · nullable	Basis of usd: "chainlink:USDC/USD" (Chainlink feed answer; details.value names the answer and its round time), "hl:ETH" (Hyperliquid mark), "hl:BTC*chainlink:WBTC/BTC", "unavailable" (no fresh price, usd null), "hyperliquid" (position / trade value).
`[].title`string	Factual one-liner, e.g. "50M USDT ($50M) moved to Binance from 0x12ab…cd34 on Ethereum" (a wallet without a sourced label is named by its address).
`[].context`string · nullable	Context from our own records, e.g. "largest USDC mint this week".
`[].from`object · nullable	Start of the window (ISO 8601 UTC) or the sending side of a movement.
`[].from.address`string · nullable	Wallet or contract address (EVM lowercase 0x…, or Bitcoin).
`[].from.label`string · nullable	Label with a cited source, else null (no sourced label).
`[].from.url`string · nullable	Explorer page.
`[].to`object · nullable	End of the window (ISO 8601 UTC) or the receiving side of a movement.
`[].to.address`string · nullable	Wallet or contract address (EVM lowercase 0x…, or Bitcoin).
`[].to.label`string · nullable	Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified).
`[].to.url`string · nullable	Link (absolute URL).
`[].txUrl`string · nullable	Transaction on the public block explorer of its chain.
`[].details`object	Readable details (chain, amount, value basis, block, venue, label source …).

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

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/movements?minUsd=5000000&limit=20"

Example response

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

{
  "data": [
    {
      "id": "p224941",
      "ts": "2026-10-27T13:10:12.766Z",
      "type": "perp_position",
      "chain": "hyperliquid",
      "asset": "BTC",
      "amount": 13.45034,
      "usd": 1078098.55,
      "priceSource": "hyperliquid",
      "title": "Whale 0x01e2…e977 reduced $1.1M BTC short on Hyperliquid",
      "context": null,
      "from": {
        "address": "0x01e273fc08012db1b75e8ca93f8139bfac2ee977",
        "label": null,
        "url": "https://hypurrscan.io/address/0x01e273fc08012db1b75e8ca93f8139bfac2ee977"
      },
      "to": null,
      "txUrl": null,
      "details": {
        "venue": "Hyperliquid (position poll)",
        "change": "decrease short · $1.1M",
        "mark": "$80,154"
      }
    },
    {
      "id": "t143459",
      "ts": "2026-10-27T13:10:11.416Z",
      "type": "big_trade",
      "chain": "hyperliquid",
      "asset": "BTC",
      "amount": 13.4453635774,
      "usd": 1077619,
      "priceSource": "hyperliquid",
      "title": "Wallet 0x01e2…e977 bought $1.1M of BTC on Hyperliquid perps (tracked whale)",
      "context": null,
      "from": {
        "address": "0x01e273fc08012db1b75e8ca93f8139bfac2ee977",
        "label": null,
        "url": null
      },
      "to": null,
      "txUrl": null,
      "details": {
        "venue": "Hyperliquid perp",
        "price": "$80,148",
        "fills": "45 fills of one taker order"
      }
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:10:12.766Z",
    "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"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/movements?cursor=<cursor>"
  }
}

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

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.