Vike Data API

Hyperliquid Liquidations

hl_liquidations

Read-onlyIdempotent

Hyperliquid liquidations, by view. fills: liquidation events, newest first, filtered by symbol, wallet, side and time. Since 2026-08-03 rows are EXACT, the liquidated wallet's own fill from the node (liq_ts the fill's millisecond, sizes what it closed, mark_price the venue's mark); older rows are INFERRED from ~5-minute position snapshots (a position over $100 whose mark was within 5% of its liquidation price and which is gone from the next snapshot; liq_ts is that snapshot's time and size/mark are the last values seen; a hand close that near liquidation counts, partial liquidations are missed); direction is the side of the position that was CLOSED (long = longs liquidated, price fell) and each row's pnl_cohort carries a pnl_cohort_basis saying how it was labelled. risk: per symbol, the share of open notional close to liquidation: percent_risk is a FRACTION from 0 to 1 despite its name, ranked by that fraction, so thin micro-cap markets can top it (read total_value_usd, or pass min_value_usd). heatmap: one symbol, where its open positions' own liquidation prices cluster, in equal-width price bins weighted by notional USD; positions outside +-50% of mark or without a liquidation price are left out and counted under coverage. Same data as GET /v1/hyperliquid/{liquidations, liquidations/risk, symbols/{symbol}/liquidation-heatmap}.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "hl_liquidations"
  }
}

Input Schema

Name	Required	Description	Default
`end`	No	ISO-8601 UTC upper bound, e.g. 2026-10-02T00:00:00Z. Used by view: fills.
`axis`	No	Cohort ladder: `size` = account-value tiers in USD, `pnl` = percentile rank of cumulative realized PnL (NOT dollars), `pnl_abs` = dollar bands of that same PnL. Used by view: risk.	size
`bins`	No	Number of equal-width price bins, minimum 5. The window is fixed at +-50% around the mark price. Max 500. Used by view: heatmap.
`view`	No	What to read. `fills`: liquidation events, newest first: exact from the node's fills since 2026-08-03, inferred from position snapshots before. `risk`: per symbol, the share of open notional close to liquidation. `heatmap`: where one symbol's open positions would liquidate, binned by price. Default `fills`.	fills
`limit`	No	Rows per page, newest first. Max by view: fills 5000, risk 500. Used by view: fills, risk.
`start`	No	ISO-8601 UTC lower bound, e.g. 2026-10-01T00:00:00Z. Used by view: fills.
`cohort`	No	One label on `axis`, spelled exactly as `hl_segments` view=cohorts lists it, e.g. `whale` (size) or `3x smart` (pnl). Omit for all wallets. Used by view: risk.
`cursor`	No	`nextCursor` from the previous page, passed back verbatim; it is null on the last page. Omit it for the first page. Used by view: fills.
`symbol`	No	Hyperliquid instrument ticker, e.g. BTC, ETH, HYPE; a HIP-3 market is `dex:TICKER`, e.g. xyz:TSLA. Used by view: fills, heatmap. Required by view: heatmap.
`wallet`	No	One wallet, to ask whether it has been liquidated. Used by view: fills.
`direction`	No	The side of the position that was CLOSED: `long` = longs liquidated (price fell), `short` = shorts liquidated. Used by view: fills.
`min_value_usd`	No	`risk` only: smallest total open notional in USD a symbol needs to be ranked. Default 0 (no floor), so thin micro-cap markets can lead; raise it to keep only markets big enough for a cascade to matter. Used by view: risk.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 1, 2026

changedInput schema / properties / view / description

Previous value: -"What to read. `fills`: liquidation events inferred from position snapshots, newest first. `risk`: per symbol, the share of open notional close to liquidation. `heatmap`: where one symbol's open positions would liquidate, binned by price. Default `fills`."New value: +"What to read. `fills`: liquidation events, newest first: exact from the node's fills since 2026-08-03, inferred from position snapshots before. `risk`: per symbol, the share of open notional close to liquidation. `heatmap`: where one symbol's open positions would liquidate, binned by price. Default `fills`."

First observedOct 25, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already covering read-only, idempotent, and non-destructive semantics, the description goes well beyond: it discloses the exact/inferred data split at 2026-08-03, the inference heuristic and its failure modes (hand closes counted, partial liquidations missed), and heatmap coverage exclusions. These are data-quality caveats an agent cannot get from annotations and would otherwise misuse the results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the tool's identity and view partition, and every clause carries information. The `fills` section, however, is one very long run-on sentence packing provenance, heuristic, direction semantics, and cohort basis, which could be split into separate sentences for faster scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the return-shape burden and does so: it names and explains `liq_ts`, `mark_price`, `direction`, `pnl_cohort`/`pnl_cohort_basis`, `coverage`, `percent_risk`, and `total_value_usd`. For a 12-parameter, three-view tool this is complete enough to call and interpret correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning by warning that `percent_risk` is a 0-1 fraction despite its name, explaining why `min_value_usd` exists (thin micro-caps topping the ranking), and clarifying `cohort` must be spelled exactly as `hl_segments` view=cohorts lists it. That cross-tool dependency is not derivable from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states the resource and immediately partitions it by `view`, then each of `fills`, `risk`, and `heatmap` gets a precise definition of what it returns. An agent can tell which view answers which question without opening the schema, and the closing line names the underlying REST endpoints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implicitly routed by view: `fills` for events, `risk` for per-symbol concentration, `heatmap` for one symbol's liquidation clusters, plus operational advice ('read `total_value_usd`, or pass `min_value_usd`'). It draws no explicit boundary against siblings like hl_position_match or hl_wallet_activity, so the agent must infer routing from those tools' own descriptions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Vike Data API tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.