---
title: "Inspect potential liquidation exposure by price"
method: GET
path: "/api/public/v1/live/liquidation-heatmap/{coin}"
tags: ["Liquidation risk"]
---

# Inspect potential liquidation exposure by price

`GET /api/public/v1/live/liquidation-heatmap/{coin}`

## Request

- Base URL: `https://api.coinversa.ai`
- URL: `https://api.coinversa.ai/api/public/v1/live/liquidation-heatmap/{coin}`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/coinversa/apis/coinversa-api/docs/api/public/v1/live/liquidation-heatmap/:coin/get.ts> (a function with typed inputs; its response is checked against the schema)

Group currently indexed positions by liquidation price around the current mark. Risk notional is potential exposure in USD, not realized liquidations or a price forecast. The timestamp is when the heatmap was computed, including when served from cache. Empty buckets with currentPrice zero mean no matching input positions. Numeric query parameters must be integers; buckets <= 0 returns an empty heatmap under the existing contract.

## Path parameters

- `coin` string, required: Exact market symbol as indexed; for example BTC or xyz:GOLD.

## Query parameters

- `buckets` integer: Number of equal price buckets. Values at or below zero return an empty heatmap; use 50 for the standard example.
- `range` integer: Percentage distance below and above current mark, not a fraction: 30 means +/-30 percent.

## Response `200`

OK

- LiquidationHeatmapBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `buckets` HeatmapBucket[], nullable, required: Price buckets ordered ascending; empty if no positions were found or bucket count is nonpositive.
    - `cumulativeLongNotional` number, double, required: Cumulative long notional from the current-price bucket downward, USD; zero for buckets above it.
    - `cumulativeShortNotional` number, double, required: Cumulative short notional from the current-price bucket upward, USD; zero below current-price bucket.
    - `longNotionalAtRisk` number, double, required: Long position notional assigned to this bucket, USD; potential exposure, not a realized loss.
    - `longPositions` integer, required: Long positions with liquidation prices in this bucket.
    - `priceHigh` number, double, required: Upper bound of this price bucket, USD per unit.
    - `priceLow` number, double, required: Lower bound of this price bucket, USD per unit.
    - `shortNotionalAtRisk` number, double, required: Short position notional assigned to this bucket, USD; potential exposure, not a realized loss.
    - `shortPositions` integer, required: Short positions with liquidation prices in this bucket.
    - `totalNotionalAtRisk` number, double, required: Sum of long and short notional at risk in this bucket, USD.
  - `coin` string, required: Market symbol queried.
  - `currentPrice` number, double, required: Mark price used to construct buckets, USD per unit; zero if there are no input positions.
  - `timestamp` integer, required: Time this heatmap was computed, Unix milliseconds. Preserved on cache hits; not a source ingestion timestamp.
  - `totalLongAtRisk` number, double, required: Total long position notional inside the requested price range, USD.
  - `totalShortAtRisk` number, double, required: Total short position notional inside the requested price range, USD.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `504`: Gateway Timeout

## Changes

- **2026-09-23** `f2eba29805e5`: 9 info
  - api tag `Liquidation risk` added
  - added the non-success response with the status `403`
  - removed the non-success response with the status `401`
  - added the optional property `reason` to the response with the `400` status
  - …5 more

[Operation history](https://skmtc.dev/coinversa/apis/coinversa-api/changes/api/public/v1/live/liquidation-heatmap/:coin/get.md)

---

[API](https://skmtc.dev/coinversa/apis/coinversa-api.md) - [All operations](https://skmtc.dev/coinversa/apis/coinversa-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coinversa/apis/coinversa-api/revisions/3454317a5830?raw)