---
title: "Get API public v1 live risk coins by coin"
method: GET
path: "/api/public/v1/live/risk/coins/{coin}"
---

# Get API public v1 live risk coins by coin

`GET /api/public/v1/live/risk/coins/{coin}`

## Request

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

## Path parameters

- `coin` string, required

## Response `200`

OK

- CoinRiskSnapshotBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `availability` RiskAvailability, required
    - `historicalClearinghouse` boolean, required
    - `liquidations` boolean, required
    - `liveCandles` boolean, required
    - `markPrices` boolean, required
    - `userActions` boolean, required
  - `avgLiquidationDistancePct` number, double
  - `coin` string, required
  - `concentrationTop5` number, double, required
  - `freshness` RiskFreshness, required
    - `historicalClearinghouse` string
    - `liquidations` string
    - `liveCandles` string
    - `livePositions` string
    - `longShort` string
    - `markPrices` string
  - `generatedAt` string, required
  - `liquidationHeatmap` LiquidationHeatmapBody, required
    - `$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.
  - `liquidationSummary7d` LiquidationSummaryBody, required
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `availability` RiskAvailability, required
      - `historicalClearinghouse` boolean, required
      - `liquidations` boolean, required
      - `liveCandles` boolean, required
      - `markPrices` boolean, required
      - `userActions` boolean, required
    - `avgClosedPnl` number, double, required
    - `avgPenaltyFee` number, double, required
    - `bucketSizeMs` integer, required
    - `byCohort` GetLiquidationSummaryByCohortRow[], nullable: Cohort (pnl_tier) split of the same window, sorted by totalNotional desc; wallets with no cohort classification aggregate under tier 'unclassified'. Only populated on GET /live/risk/liquidations/summary — omitted from the other consumers of this shape (risk overview, coin risk snapshot/history) to keep those hot paths from running an extra query.
      - `count` integer, required
      - `tier` string, required
      - `totalClosedPnl` unknown, required
      - `totalNotional` unknown, required
      - `wallets` integer, required
    - `byCoin` GetLiquidationSummaryByCoinRow[], nullable, required
      - `coin` string, required
      - `count` integer, required
      - `totalClosedPnl` unknown, required
      - `totalNotional` unknown, required
      - `totalPenaltyFees` unknown, required
    - `coin` string
    - `count` integer, required
    - `freshness` RiskFreshness, required
      - `historicalClearinghouse` string
      - `liquidations` string
      - `liveCandles` string
      - `livePositions` string
      - `longShort` string
      - `markPrices` string
    - `generatedAt` string, required
    - `longEvents` integer, required: Count of LONG liquidation events in the window (longEvents+shortEvents=count).
    - `longNotional` number, double, required: Notional of liquidated LONG positions in the window (side split of totalNotional; longNotional+shortNotional=totalNotional).
    - `shortEvents` integer, required: Count of SHORT liquidation events in the window.
    - `shortNotional` number, double, required: Notional of liquidated SHORT positions in the window (side split of totalNotional).
    - `since` string, required
    - `timeline` GetLiquidationSummaryTimelineRow[], nullable, required
      - `bucketStart` integer, required
      - `count` integer, required
      - `totalClosedPnl` unknown, required
      - `totalNotional` unknown, required
      - `totalPenaltyFees` unknown, required
    - `totalClosedPnl` number, double, required
    - `totalNotional` number, double, required
    - `totalPenaltyFees` number, double, required
    - `wallets` integer, required
  - `longShort` CoinLongShortBody, required
    - `$schema` string, uri: A URL to the JSON Schema for this object.
    - `avgLongLeverage` number, double
    - `avgLongSize` number, double, required
    - `avgShortLeverage` number, double
    - `avgShortSize` number, double, required
    - `coin` string, required
    - `concentrationTop5` number, double, required
    - `longAccounts` integer, required
    - `longUnrealizedPnl` number, double, required
    - `longVolume` number, double, required
    - `maxLeverage` number, double
    - `netBias` number, double, required
    - `ratio` number, double, required
    - `sampleSize` integer, required
    - `shortAccounts` integer, required
    - `shortUnrealizedPnl` number, double, required
    - `shortVolume` number, double, required
    - `timestamp` integer, required
    - `topLongs` LSTopPosition[], nullable, required
      - `address` string, required
      - `notional` number, double, required
      - `pnl` number, double, required
      - `size` number, double, required
    - `topShorts` LSTopPosition[], nullable, required
      - `address` string, required
      - `notional` number, double, required
      - `pnl` number, double, required
      - `size` number, double, required
    - `totalUnrealizedPnl` number, double, required
    - `volumeRatio` number, double, required
  - `market` GetCoinStatsRow, required
    - `avgLongLeverage` number, double, required
    - `avgShortLeverage` number, double, required
    - `coin` string, required
    - `longNotional` number, double, required
    - `longPositions` integer, required
    - `shortNotional` number, double, required
    - `shortPositions` integer, required
    - `totalOi` number, double, required
    - `totalPositions` integer, required
    - `totalUnrealizedPnl` number, double, required
    - `uniqueWallets` integer, required
  - `nearLiquidationNotional` number, double, required
  - `nearLiquidationPositions` integer, required
  - `recentLiquidations` GetRecentLiquidationsRow[], nullable, required
    - `address` unknown, required
    - `closedPnl` number, double, nullable, required
    - `coin` string, required
    - `liquidator` unknown, required
    - `penaltyFee` number, double, nullable, required
    - `pnlTier` string, nullable, required
    - `timestampMs` integer, required
  - `sizeBreakdown` GetPositionSizeBreakdownRow[], nullable, required
    - `longCount` integer, required
    - `longNotional` number, double, required
    - `positionCount` integer, required
    - `shortCount` integer, required
    - `shortNotional` number, double, required
    - `sizeBucket` string, required
    - `sortOrder` integer, required
    - `totalNotional` number, double, required
  - `topPositions` GetTopPositionsRow[], nullable, required
    - `address` unknown, required
    - `coin` string, required
    - `entryPx` number, double, nullable, required
    - `fundingSinceOpen` number, double, nullable, required
    - `leverage` number, double, nullable, required
    - `leverageType` string, nullable, required
    - `liquidationPx` number, double, nullable, required
    - `marginUsed` number, double, nullable, required
    - `markPx` number, double, nullable, required
    - `notional` number, double, nullable, required
    - `openedAtRaw` integer, nullable, required
    - `pOpenedAt` string, nullable, required
    - `pUpdatedAt` string, nullable, required
    - `pnlTier` string, nullable, required
    - `roe` number, double, nullable, required
    - `side` string, required
    - `size` number, double, nullable, required
    - `sizeTier` string, nullable, required
    - `traderTotalPnl` string, required
    - `traderTotalTrades` integer, nullable, required
    - `traderWinRate` number, double, nullable, required
    - `unrealizedPnl` number, double, nullable, required

## 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`: 8 info
  - 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
  - added the optional property `reason` to the response with the `404` status
  - …4 more

[Operation history](https://skmtc.dev/coinversa/apis/coinversa-api/changes/api/public/v1/live/risk/coins/: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)