> ## 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 totals by market and window > GET /v1/liquidations/summary returns long and short USD liquidated on Hyperliquid per window (15m to 7d) and market, with counts, wallets and the largest one. ## OpenAPI ````yaml GET /v1/liquidations/summary 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/summary: get: tags: - Market Data summary: Liquidation summary by market and window description: > Long and short liquidated USD, liquidation count, wallets and the largest liquidation, per market and in total, over trailing windows. Liquidation fills are grouped into events (one wallet, one market, one minute). Cached for 15 seconds. The windows end now: `from` and `to` are not read, and a call that sends them gets a `notice` saying so (for a past range, use `GET /v1/liquidations`). Guessed paths such as `/v1/liquidations/aggregate` and `/v1/summary/liquidations` are answered by this endpoint. operationId: liquidationSummary parameters: - name: market in: query description: One market or a comma list, up to 50. Omit for every market. schema: type: string example: BTC-PERP ETH-PERP: null - name: windows in: query description: Comma list of 15m, 1h, 4h, 12h, 24h, 7d. Keyless calls reach 24h. schema: type: string default: 1h 4h: null 24h: null - name: bucket in: query description: >- 15m, 1h or 4h. Adds a long/short series per market over the longest window; needs market with 1 to 10 markets. schema: type: string responses: '200': description: Totals per window. content: application/json: schema: $ref: '#/components/schemas/LiquidationSummary' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: LiquidationSummary: type: object properties: as_of: type: integer format: int64 windows: type: array items: type: object properties: window: type: string example: 24h from: type: integer format: int64 total: $ref: '#/components/schemas/LiquidationTotals' largest: $ref: '#/components/schemas/LargestLiquidation' markets: type: array description: Markets with liquidations in the window, largest first. items: allOf: - $ref: '#/components/schemas/LiquidationTotals' - type: object properties: market: type: string largest: $ref: '#/components/schemas/LargestLiquidation' series: type: object description: >- With bucket, per market, the long and short USD and count per step over the longest window. additionalProperties: type: array items: type: object properties: timestamp: type: integer format: int64 long_usd: type: number short_usd: type: number liquidations: type: integer LiquidationTotals: type: object properties: long_usd: type: number description: Notional of long positions liquidated, USD. short_usd: type: number description: Notional of short positions liquidated, USD. liquidations: type: integer description: Liquidation events (one wallet, one market, one minute). wallets: type: integer description: Distinct wallets liquidated. LargestLiquidation: type: object properties: market: type: string example: BTC-PERP side: type: string enum: - long - short description: The position that was closed. usd: type: number price: type: number description: Average fill price of the liquidation. address: type: string timestamp: type: integer format: int64 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) 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) Forbidden: description: Your tier does not include this feature. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TIER_FORBIDDEN message: Export requires Builder tier or above 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. InternalError: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An unexpected error occurred 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.