liquidationRiskCross delivers when a position’s distance to its liquidation price crosses a threshold, and liquidationRisk when that distance has moved by a number of points. Two watch a whole market: liquidationExposure delivers when enough notional has liquidation levels within a price move from the mark, and liquidationMap delivers the market’s full liquidation map once the mark has moved by a percentage.
All four need Starter or above, and deliver the way every other subscription type does: a signed POST to your URL, or the inbox. They describe exposure — they are not a recommendation to trade.
Delivery examples are illustrative: the values are made up.
Not executed liquidations
liquidations and liquidationsByUser deliver liquidations that happened. The four types on this page are about positions that have not been liquidated:
Timing
The service checks about once a minute. Each check reads positions and liquidation levels as last stored — it does not follow every price tick.- A move that happens and reverses between two checks is not seen, and nothing is replayed after an outage.
- The wallet types use the mark price and the liquidation price stored with each position when the wallet was last refreshed. The market can move before the next refresh, so a stored distance can lag it.
updatedAtin a delivery is the time the position was stored. - The market types value every position at one mark price tick for the market, and need a tick less than five minutes old. Without one they send nothing — not a zero.
markTimein a delivery is the tick’s time;positionsOldestUpdatedAtandpositionsNewestUpdatedAtsay how old the positions behind the numbers are. - Liquidation levels are not recomputed between refreshes. A cross-margin position’s level moves with the account’s collateral, and that shows only after the wallet is refreshed.
- A check that cannot read its data changes nothing: no delivery, and no change of state.
The four types
Arguments
- Every number is sent as a string, the two integers included:
"buckets": "50". - These are a
400: more than one wallet inuser;priceMovePctthat is not above0or is above100;resetNotionalaboveminNotional;bucketsorrangethat is not a whole number in its range ("1.5","0","201"); and an argument the type does not declare, such ascoinon a wallet type. - The definitions advertise the limits:
minItems: 1andmaxItems: 1onuser,max: 100onpriceMovePct,minandmaxonbucketsandrange(definitions). coinis not checked against a list of markets when you create the subscription: a symbol with no recent mark price is accepted and delivers nothing. A wallet with no open positions on record is accepted too, and delivers nothing.
Distance to liquidation
The two wallet types measure one number per position,liquidationDistancePct:
"5" means 5%, not 0.05. Long and short positions use the same absolute distance, and a smaller number is closer to liquidation. With a mark of 100, a long with its liquidation price at 95 and a short with its liquidation price at 105 are both at 5.
- Thresholds,
pointsand the filter are compared with exact decimal arithmetic on the stored prices. TheliquidationDistancePctin a delivery is the same distance written with 18 decimal places. - A position without a positive mark price and a positive liquidation price has no distance. It does not fire and it is not treated as zero.
- The distance is absolute, so by itself it does not say which side of the liquidation price the mark is on.
Filters
OnlyliquidationRisk takes a filter:
gt / gte / lt / lte bounds, as decimal strings — the rules on Filters.
- On
liquidationRisk, a position that does not pass is not delivered and its baseline does not move. liquidationRiskCross,liquidationExposureandliquidationMaptake no filters — their condition is inargs, and extra predicates are refused.
Delivered fields
The frame is the one every type uses —channel, seq, subscriptionId, data (the delivered frame). Decimal values are strings; counts and times are numbers.
Wallet types
OnliquidationRiskCross and liquidationRisk, data holds one object: the wallet and the positions that fired. Positions that did not fire are left out.
liquidationExposure events
One event per direction that fired, so with direction: "both" one delivery can hold two.
liquidationMap events
One event: the whole map.
abs(size) * currentPrice — the stored size valued at the check’s mark, not a realised loss. Positions without a liquidation level are left out, and so are levels the mark has already reached or that are on the wrong side of it.
liquidationRiskCross
A position’s distance to its liquidation price crossing a threshold. direction picks the crossing you want: below is the position getting closer to liquidation, above is it moving away.
belowfires when the previous distance was at or above the threshold and the new one is below it;aboveis the inverse. Merely reaching the threshold is not a crossing: with a threshold of"5", a distance of exactly5fires nothing, and4does.- A position’s first valid observation fires if the distance is already strictly on the side you asked for — with
initial: trueand noprevious. Withboth, either side qualifies; exactly at the threshold does not. - Staying on the same side does not repeat, however often the position is refreshed.
- Each position is followed on its own. One that closes, changes side or loses its prices starts over: its next valid observation is a first observation again.
liquidationRisk
A position’s distance to its liquidation price moving by at least points percentage points from a baseline. The baseline is the reading you were last notified about.
- The first observation of a position that passes the filter fires, with
initial: true, and becomes that position’s baseline. Without a filter, that is the first valid observation. - After that the rule is
abs(distance - baseline distance) >= points, and the position must still pass the filter. Small moves accumulate against the same baseline, in either direction: withpoints: "2", readings of4,3.5,3and2fire at4(initial) and again at2, withchangePoints: "-2". - Only a notification moves the baseline. A reading the filter rejects does not, and neither does a notification about another position.
- Each position has its own baseline. One that closes, changes side or loses its prices starts over.
previous is the baseline, which can be many checks old:
liquidationExposure
How much notional on a market has liquidation levels within a price move from the mark. It fires when that amount reaches minNotional.
downsums long positions withtargetPrice <= liquidationPx < currentPrice;upsums short positions withcurrentPrice < liquidationPx <= targetPrice.targetPriceis the mark moved bypriceMovePct.- It is the total along the whole move, not the content of one map bucket.
- It fires when exposure becomes at least
minNotional— on the first observation if that one already qualifies — and not again at every check while it stays there. A price move or a change in positions can both cause it. - To fire again, exposure must first fall strictly below
resetNotional; reaching it is not enough. SetresetNotionallower thanminNotionalto stop repeats when exposure hovers around the threshold. There is no cooldown. - With
both, each direction keeps its own state, and both can fire in one delivery.
liquidationMap
The market’s full liquidation map — notional by price bucket, below and above the mark — sent when the mark has moved at least priceChangePct from a reference price.
- The first observation only records the reference price. No map is sent then.
- A later check sends the map when
100 * abs(currentPrice - referencePrice) / referencePrice >= priceChangePct. The reference then becomes that send’s mark. - With
priceChangePct: "1"and a first mark of100, marks of100.4and100.8send nothing and101sends a map. A later fall to99.99sends another: it is 1% below101. - The move is measured from the reference — not between two consecutive checks, not as a candle change and not over a rolling window. A change in positions without a price move sends nothing.
- The map covers
rangepercent below and above the mark, cut intobucketsequal price bands. Every bucket is sent, empty ones included.
State and delivery
- Each subscription keeps its own state — per position on the wallet types, per direction on
liquidationExposure, one reference price onliquidationMap. A check that shows nothing new changes nothing and repeats nothing. - Unavailable is not zero. A wallet type skips a position without usable prices; a market type sends nothing without a recent mark price tick. A wallet with no open positions on record delivers nothing — which is not proof that the wallet exists or that its data is fresh.
seqon these four types is the Unix time, in microseconds, at which the service first read that observation. It is not a block height, and it is not comparable with theseqof any other type (the delivered frame).- Deliveries are durable, as on
priceCross: the subscription’s state and the pending delivery — or the inbox message — commit together, and HTTP deliveries wait in the same outbox, at most 32 pending per subscription (Plan limits). If a subscription’s share is full, a new notification is rejected and logged, and its state does not advance. Delivery is at least once: deduplicate onwebhook-id. - Subscriptions are immutable. Delete and recreate one to change it; that also clears its state. A recreated wallet or
liquidationExposuresubscription can fire again on its first observation, and a recreatedliquidationMaprecords a new reference price first.

