# Liquidation price map · API reference · Femtos

> Liquidation prices of every open position, from Hyperliquid's formula on each account's state, bucketed like the stop map. GET /v1/hypercore/liquidation-map on HyperCore: parameters, response fields and a live call per layer.

- Base URL: `https://api.femtos.xyz/v1` (REST) · `wss://api.femtos.xyz/v1/ws` (WebSocket) · MCP: `https://api.femtos.xyz/mcp`
- Auth: `Authorization: Bearer $FEMTOS_KEY`. Free key: https://femtos.xyz/account/new (browser), or with
  no browser: `GET https://femtos.xyz/accounts/agent/challenge`, solve its proof of work, then `POST https://femtos.xyz/accounts/agent/signup`
  (https://femtos.xyz/agents.md#agent-onboarding)
- Decimals are exact strings, times Unix milliseconds, addresses lowercase `0x`
- Whole API in one file: https://femtos.xyz/agents.md · OpenAPI: https://api.femtos.xyz/v1/openapi.json · Index: https://femtos.xyz/llms.txt
- Page with live calls: https://femtos.xyz/reference/liquidation-map

## Liquidation price map — GET `/v1/hypercore/liquidation-map`

Liquidation prices of every open position, from Hyperliquid's formula on each account's state, bucketed like the stop map.

Layers: HyperCore. Not on Elysium or HyperEVM: served on HyperCore only.
Page with live calls: https://femtos.xyz/reference/liquidation-map?layer=hypercore

| Param | In | Example or values | Meaning |
|---|---|---|---|
| `coin` | query | `BTC` | HyperCore perp coin: BTC, xyz:TSLA |
| `buckets` | query | `40` | Most buckets (width rounded up to a round number); not with step |
| `step` | query | (optional) | Bucket width in price units, instead of buckets (at most 400 buckets) |
| `range_pct` | query | `10` | Half-width of the grid around the mark, percent, (0, 100] |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/hypercore/liquidation-map?coin=BTC&buckets=40&range_pct=10"
```

| Field | Type | Meaning |
|---|---|---|
| `buckets[]` | object | Ascending price; empty when the mark is unknown: {pxLo, pxHi, long, short} |
| `below` | object | long: liquidated by a forced sell as price falls to it; short: by a forced buy as price rises to it: {long, short} |
| `above` | object | long: liquidated by a forced sell as price falls to it; short: by a forced buy as price rises to it: {long, short} |
| `totals` | object | long: liquidated by a forced sell as price falls to it; short: by a forced buy as price rises to it: {long, short} |
| `coverage` | object | How much of the open interest the map holds: every account's positions at `height`, each liquidation price from Hyperliquid's formula on the account state; none for portfolio-margin cross accounts and positions that cannot be liquidated: {positions, withLiqPx, sz, szWithLiqPx, share, note} |
| `asOf` | ms | Time of `height` (Unix ms) |
| `height` | int | Block the positions are at: the node's latest state (one every 10,000 blocks, ~12 min) rolled forward with every fill, funding payment and ledger update since, a few seconds behind the chain; the state itself while the roll is not running |
| `baseHeight` | int | Block of that node state (= height when not rolled forward) |
| `markPx` | decimal \| null | Mark: last trade |
| `rangePct` | decimal | range_pct applied |
| `step` | decimal \| null | Bucket width |

## Related (Price-level maps)

- [Liquidation map stream](https://femtos.xyz/reference/ws/liquidations-map.md) `WS hc.liquidations.map`: The GET /api/hypercore/liquidation-map map, pushed whole on subscribe and every 5 s when it changes. (HyperCore)
- [Forced flow](https://femtos.xyz/reference/forced-flow.md) `GET /v1/hypercore/forced-flow`: Stop-loss / take-profit orders and liquidations on the same buckets: the cascade (stops + liquidations, with the move) and the take-profits (against it) at each price. (HyperCore)
- [Forced flow stream](https://femtos.xyz/reference/ws/forced-flow.md) `WS hc.forced_flow.map`: The GET /api/hypercore/forced-flow map, pushed whole on subscribe and every 5 s when it changes. (HyperCore)
- [Stop map stream](https://femtos.xyz/reference/ws/stops-map.md) `WS hc.stops.map`: The GET /api/hypercore/stops map, pushed whole on subscribe and every 5 s when it changes. (HyperCore)

Every page: https://femtos.xyz/reference.md