Map where the positions of a market would be liquidated
/v1/chains/{chain}/perpl/markets/{market}/liquidation-mapCall this to see at which prices the open positions of a market get liquidated. buckets is the dense list of price buckets from mark * (1 - range_pct%) up to mark * (1 + range_pct%). Their edges are multiples of bucket_bps basis points of the mark away from the mark, so one bucket starts exactly at the mark, and the two outermost buckets are narrower when the range is not a multiple of the width. Each bucket holds the notional at the mark (long_notional_usd, short_notional_usd) and the number of accounts (long_accounts, short_accounts) whose liquidation price lies in [price_from, price_to). The top edge of the last bucket belongs to it. Longs normally liquidate below the mark and shorts above it. A position that is already liquidatable has its liquidation price on the other side of the mark and is counted there.
beyond_range adds up the positions whose liquidation price lies outside the range, with their notional and count per side. cumulative gives, for each whole move of move_pct 1 to range_pct percent, the notional and the number of positions that would be liquidated by a fall of that size (long) or a rise of that size (short). It counts every position, also those beyond the range or already liquidatable. Both curves never decrease.
bucket_bps is 5 to 500, 25 by default, and range_pct is 1 to 50, 20 by default.
Path parameters
| Name | Type | Description |
|---|---|---|
chainRequired | string | The chain, as a CAIP-2 chain ID. Only Monad, |
marketRequired | string | A market, as its symbol in any case ( |
Query parameters
| Name | Type | Description |
|---|---|---|
bucket_bps | integerDefault 25 | The width of a price bucket in basis points of the mark, from 5 to 500. The default is 25, which is 0.25%. |
range_pct | integerDefault 20 | How far the map reaches on each side of the mark, in percent, from 1 to 50. The default is 20. |
Response
The answer, wrapped in the {data, meta, links} envelope. data.kind is perpl_liquidation_map. meta.as_of names the snapshot block.
| Field | Type | Description |
|---|---|---|
| beyond_range | object | |
| bucket_bps | integer | |
| buckets | array of objects | The price buckets in ascending order of price, with no gaps. |
| chain | string | The CAIP-2 id of the chain. |
| coverage | array of strings | The codes of the limits that apply to this answer, in a fixed order. It is empty when none applies. The status route explains each code. |
| cumulative | object | |
| kind | string | perpl_liquidation_map |
| mark | string | A price, or a size in the base asset, as a decimal string with no trailing zeros. Values read straight from the chain are exact, and computed values have at most 15 significant digits. |
| perp_id | integer | |
| range_pct | integer | |
| symbol | string |
Cost
1 credit. The time limit is 5 seconds.
Errors
| Status | Code |
|---|---|
| 400 | invalid_query |
| 404 | not_foundunsupported_chain |
| 429 | rate_limitedcredits_exhausted |
| 500 | internal |
| 503 | upstream_unavailable |
| 504 | deadline_exceeded |
400 invalid_query for a value out of range or an unknown parameter, 404 not_found, 404 unsupported_chain, 503 and 504 as elsewhere.