> ## Documentation Index > Fetch the complete documentation index at: https://docs.ironflow.sh/llms.txt > Use this file to discover all available pages before exploring further. # Hyperliquid liquidation map > GET /v1/liquidations/map returns where open Hyperliquid perp positions would be liquidated, by price, with running totals, from our node's state snapshot. The map is built from every open perp position in our Hyperliquid node's state snapshot, which the node writes about every 12 minutes. `snapshot.height` and `snapshot.age_s` say which snapshot the positions come from, and `as_of` when they were last priced. How liquidation prices are found: * Liquidation prices follow Hyperliquid's maintenance margin rules. * For cross-margin positions they assume the account's other positions stay at mark. In a real move correlated markets fall together, so cross-margin accounts are liquidated earlier than these prices. * Portfolio-margin accounts use Hyperliquid's own `liquidationPx`. `coverage.portfolio_margin_pct` is their share of the market's notional. * Notional is size times liquidation price. `cum_long_usd` on a level below the mark is every long liquidated between the mark and that level: what a fall to that price would take out. `cum_short_usd` does the same for shorts above the mark. For a chart of liquidations that already happened, use [liquidation levels](https://docs.ironflow.sh/api-reference/analytics/liquidation-levels.md). ## OpenAPI ````yaml GET /v1/liquidations/map openapi: 3.1.0 info: title: Ironflow API version: 1.0.0 description: > Hyperliquid market data from Ironflow's own nodes: tick-level fills and trades, candles, funding rates, liquidations, mark prices, open interest, markets and wallet analytics over REST, live Server-Sent Events streams and read-only SQL. One schema across native HL perps, HIP-3 builder markets, HIP-4 outcome contracts and HL spot. The same data is a hosted MCP server for AI agents at `https://mcp.ironflow.sh/mcp`, and agents with a USDC wallet on Base can pay per call with x402, no key: the data GET endpoints are also served at `/x402/v1/...` (discovery: `https://api.ironflow.sh/openapi.json` and `https://api.ironflow.sh/.well-known/x402`). **Base URL:** `https://api.ironflow.sh` **Authentication:** Read endpoints work without a key (keyless access) or with a Bearer token in the `Authorization` header. Writes always need a key. ``` Authorization: Bearer if_your_api_key ``` Get a free key at https://ironflow.sh/key. **Access levels:** | Access | Requests per minute | History | Max range per request | |---|---|---|---| | No key | 30 per IP (2,000 a day) | 24 hours | 1 hour | | Free key | 60 | 30 days | 6 hours | | Explorer | 100 | 90 days | 24 hours | | Builder | 1,000 | 1 year | 7 days | | Enterprise | 10,000 | full | unlimited | Without a market filter, high-volume endpoints allow at most 4 hours per request. `/v1/trades` filtered to one perp or spot market allows 24 hours per request without a key and on a free key. A header that is present but malformed returns 401; keyless access applies only when no `Authorization` header is sent. **Data availability:** fills and trades start on 25 May 2025; other datasets start later (funding 2025-09-27, open interest and mark prices 2026-04-29). Bulk history is free to download from https://huggingface.co/ironflow. **Timestamps:** All timestamps are Unix milliseconds (int64). **Pagination:** Paginated endpoints return a `cursor` in `pagination.next_cursor`. Pass it as the `cursor` query parameter to fetch the next page. When `pagination.has_more` is `false`, you have reached the last page. **Notices:** a successful JSON object may start with `notice`, the `X-Ironflow-Notice` header in the body: what was served when it differs from what was asked (a keyless sample, a shortened history, a guessed path) and how to get the rest. **Guessed paths:** a few paths callers guess are answered by the endpoint they mean, with a `notice` and the `X-Ironflow-Canonical` header naming it: `/v1/liquidations/aggregate`, `/v1/summary/liquidations` and similar by `/v1/liquidations/summary`, `/v1/liquidations/buckets` and `heatmap` by `/v1/analytics/liquidation-levels`, and `/v1/liquidations/map/BTC-PERP` by `/v1/liquidations/map?market=BTC-PERP`. A path with trailing `.`, `,`, `;` or `)` (`/v1/query.`, copied from a sentence) is answered by the endpoint without them, with the same method, query and body. OpenAI-style paths (`/v1/models`, `/v1/chat/completions`) answer 404: this is not an LLM API, and agents use the MCP server above. contact: name: Ironflow Support url: https://ironflow.sh servers: - url: https://api.ironflow.sh description: Production security: - bearerAuth: [] - {} tags: - name: Market Data description: Historical tick-level market data stored in ClickHouse. - name: Analytics description: >- Aggregated analytics. Net flows, funding stats and the liquidation map markets work without a key; liquidation levels, the liquidation map and the vault leaderboard return a sample without one; order flow needs a key (a free key works). - name: Cohorts description: Predefined and custom address groups for filtering market data. - name: Alerts description: >- Liquidation alerts that Ironflow posts to your webhook, Discord channel, Slack channel or Telegram chat. - name: Ironbox description: >- Secure, sandboxed environments in Tokyo, next to Hyperliquid, where a trading agent runs with Ironflow's data, analytics, alerts and execution. Any API key, free included. - name: Query description: >- Read-only ClickHouse SQL over curated Hyperliquid tables (hl.*), limited by tier. - name: Billing description: >- Paid plans, paid in USDC on Hyperliquid or with x402 on Base. No card, no account page. - name: System description: Health checks and metadata endpoints. - name: TradingApp description: >- The trading terminal's own endpoints (terminal.ironflow.sh), wallet-session auth. Not part of the public data API; left out of the docs copy. paths: /v1/liquidations/map: get: tags: - Analytics summary: Liquidation map (where open positions would be liquidated) description: > Where open Hyperliquid perp positions would be liquidated, by price, now: longs below the mark, shorts above it. Built from every open position in our node's state snapshot, which the node writes about every 12 minutes. `snapshot` names the snapshot and `as_of` is when the positions were last priced. Each level gives the notional (size times liquidation price) and position count liquidated in that price range, and `cum_long_usd` / `cum_short_usd`: everything liquidated between the mark and that level, which is what a move to that price would take out. The service sums positions on a grid of 0.25% of mark; each grid level is spread over the `bucket_size` buckets it overlaps in proportion to the overlap, so notional totals stay exact and position counts stay whole. Without a key you get a sample: the 10 largest levels within 10% of mark, with a `notice`. Any key (a free key from https://ironflow.sh/key works) returns every level out to `range_pct`. The map is cached for 10 seconds. When the map service does not answer, the last map (up to 30 minutes old) is returned with `stale: true`; with nothing to return the answer is 503 with `Retry-After`. GET /v1/liquidations/map/markets lists the markets. `/v1/liquidations/map/BTC-PERP` is answered as `?market=BTC-PERP`. operationId: getLiquidationMap parameters: - name: market in: query required: true description: >- Perp symbol (BTC-PERP, xyz:NVDA-PERP) or Hyperliquid coin name (BTC, xyz:NVDA). schema: type: string example: BTC-PERP - name: bucket_size in: query description: > Price bucket width. `auto` is about 0.25% of mark rounded to 1, 2 or 5 times a power of ten (200 for BTC near 75,000, 0.2 for HYPE near 78). A number sets the width; one finer than the map's grid is raised to the auto width, with a notice. schema: type: string default: auto example: '500' - name: range_pct in: query description: >- How far from the mark to cover, in percent each way. Keyless calls cover 10. schema: type: number exclusiveMinimum: 0 maximum: 50 default: 20 - name: side in: query description: Longs, shorts or both. schema: type: string enum: - both - long - short default: both responses: '200': description: The liquidation map. headers: X-Ironflow-Notice: description: >- Present on keyless calls (a sample) and when bucket_size was raised. schema: type: string content: application/json: schema: $ref: '#/components/schemas/LiquidationMap' '400': $ref: '#/components/responses/BadRequest' '404': description: No map for this market (unknown, not a perp, or no open positions). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: >- no liquidation map for "HYPE/USDC": the map covers Hyperliquid perps with open positions, such as BTC-PERP or xyz:NVDA-PERP. GET /v1/liquidations/map/markets lists them '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/LiquidationMapUnavailable' components: schemas: LiquidationMap: type: object required: - market - mark_px - as_of - snapshot - bucket_size - range_pct - side - levels - coverage - stale - method properties: notice: type: string description: >- Present on keyless calls, which return a sample, and when bucket_size was raised. market: type: string example: BTC-PERP mark_px: type: number example: 75782 description: The mark the liquidation prices were computed against as_of: type: string format: date-time example: '2026-11-06T16:48:30Z' description: When the positions were last priced snapshot: type: object required: - height - time - age_s description: The node state snapshot the positions come from. properties: height: type: integer format: int64 example: 1211490000 description: Block height of the snapshot time: type: string format: date-time example: '2026-11-06T16:47:28Z' age_s: type: integer example: 62 description: Seconds since the snapshot counted when this answer was made: null bucket_size: type: number example: 200 range_pct: type: number example: 20 description: The range covered in percent of mark each way: null side: type: string enum: - both - long - short levels: type: array description: >- Price buckets holding positions, from the lowest price to the highest. items: $ref: '#/components/schemas/LiquidationMapLevel' coverage: type: object description: How much of the market's open notional the map prices, and how. properties: notional_usd: type: number example: 3286600394 description: Open notional of the market both sides: null with_liq_px_pct: type: number example: 98.1 description: Share of it that has a liquidation price portfolio_margin_pct: type: number example: 6 description: >- Share priced by Hyperliquid's own liquidationPx (portfolio-margin accounts) unknown_mode_pct: type: number example: 0.5 description: Share from accounts whose margin mode is not known yet stale: type: boolean description: >- True when the map service did not answer and an older map is returned method: type: string description: How the map is made example: market: BTC-PERP mark_px: 75782 as_of: '2026-11-06T16:48:30Z' snapshot: height: 1211490000 time: '2026-11-06T16:47:28Z' age_s: 62 bucket_size: 200 range_pct: 20 side: both levels: - price_lo: 72600 price_hi: 72800 long_usd: 21480000 long_positions: 412 short_usd: 0 short_positions: 0 cum_long_usd: 208900000 cum_short_usd: 0 - price_lo: 78800 price_hi: 79000 long_usd: 0 long_positions: 0 short_usd: 9800000 short_positions: 61 cum_short_usd: 62400000 cum_long_usd: 0 coverage: notional_usd: 3286600394 with_liq_px_pct: 98.1 portfolio_margin_pct: 6 unknown_mode_pct: 0.5 stale: false method: >- Every open position from our node's state snapshot. Liquidation prices follow Hyperliquid's maintenance margin rules; for cross-margin positions they assume the account's other positions stay at mark. Portfolio-margin accounts use Hyperliquid's own liquidationPx. Notional is size times liquidation price. In a real move correlated markets fall together, so cross-margin accounts are liquidated earlier than these prices. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code. example: RATE_LIMIT_EXCEEDED message: type: string description: Human-readable error description. example: Rate limit exceeded. Retry after 60 seconds. upgrade: type: object description: >- On a limit a higher plan lifts, the next plan, its price, what it lifts and the call that gets it. ironbox: type: object description: >- On a rate limit, the keyless daily cap, the stream limit and the SQL time budget, how to run the agent in an Ironbox instead. properties: why: type: string example: >- No rate limits inside an Ironbox: your agent runs next to Hyperliquid with the data on the box. create: type: string example: POST https://api.ironflow.sh/v1/ironbox url: type: string format: uri example: https://ironflow.sh/ironbox?utm_source=api stream: type: string description: >- On the keyless daily limit of `/v1/liquidations` and `/v1/trades`, the live stream that replaces polling. example: >- GET https://api.ironflow.sh/v1/liquidations/stream (no daily limit for keyless streams) LiquidationMapLevel: type: object required: - price_lo - price_hi - long_usd - long_positions - short_usd - short_positions - cum_long_usd - cum_short_usd properties: price_lo: type: number example: 72600 price_hi: type: number example: 72800 long_usd: type: number example: 21480000 description: >- Notional of longs liquidated in this range (size times liquidation price) long_positions: type: integer example: 412 short_usd: type: number example: 0 short_positions: type: integer example: 0 cum_long_usd: type: number example: 208900000 description: Longs liquidated from the mark down to this level cum_short_usd: type: number example: 0 description: Shorts liquidated from the mark up to this level responses: BadRequest: description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: BAD_REQUEST message: market is required (e.g. BTC-PERP) RateLimited: description: Rate limit exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Retry after 60 seconds. LiquidationMapUnavailable: description: >- The map is not ready (its service is starting) or its service did not answer and no recent map is cached. Retry after the Retry-After seconds. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 30 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UPSTREAM_UNAVAILABLE message: >- the liquidation map is not available right now (it is being built or its service did not answer); retry in 30 seconds securitySchemes: bearerAuth: type: http scheme: bearer description: >- Ironflow API key, format `if_xxxx`. Free keys at https://ironflow.sh/key. Optional on read endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.