Skip to main content
Four subscription types watch potential liquidation exposure — positions that are still open, and how far the price is from the level where they would be liquidated. Two watch one wallet: 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: They are not predictions, and not a guarantee that a position will be liquidated. A liquidation level is the price stored for a position when its wallet was last refreshed; the position can be closed, reduced or given more margin before the price gets there. A distance is not a probability either.

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. updatedAt in 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. markTime in a delivery is the tick’s time; positionsOldestUpdatedAt and positionsNewestUpdatedAt say 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 in user; priceMovePct that is not above 0 or is above 100; resetNotional above minNotional; buckets or range that is not a whole number in its range ("1.5", "0", "201"); and an argument the type does not declare, such as coin on a wallet type.
  • The definitions advertise the limits: minItems: 1 and maxItems: 1 on user, max: 100 on priceMovePct, min and max on buckets and range (definitions).
  • coin is 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:
It is in percent: "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, points and the filter are compared with exact decimal arithmetic on the stored prices. The liquidationDistancePct in 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

Only liquidationRisk takes a filter: It takes an exact value or 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, liquidationExposure and liquidationMap take no filters — their condition is in args, 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

On liquidationRiskCross and liquidationRisk, data holds one object: the wallet and the positions that fired. Positions that did not fire are left out. Each position:

liquidationExposure events

One event per direction that fired, so with direction: "both" one delivery can hold two.

liquidationMap events

One event: the whole map. Each bucket uses the field names of the REST API’s liquidation heatmap: On both market types notional is 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.
  • below fires when the previous distance was at or above the threshold and the new one is below it; above is the inverse. Merely reaching the threshold is not a crossing: with a threshold of "5", a distance of exactly 5 fires nothing, and 4 does.
  • A position’s first valid observation fires if the distance is already strictly on the side you asked for — with initial: true and no previous. With both, 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.
Create
A crossing from 5.5% to 4%:
Delivery

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: with points: "2", readings of 4, 3.5, 3 and 2 fire at 4 (initial) and again at 2, with changePoints: "-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.
Create
previous is the baseline, which can be many checks old:
Delivery

liquidationExposure

How much notional on a market has liquidation levels within a price move from the mark. It fires when that amount reaches minNotional.
  • down sums long positions with targetPrice <= liquidationPx < currentPrice; up sums short positions with currentPrice < liquidationPx <= targetPrice. targetPrice is the mark moved by priceMovePct.
  • 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. Set resetNotional lower than minNotional to 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.
Create
This asks for at least 6 million of long notional with liquidation levels along a 3% fall from the mark. A first observation that already qualifies:
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 of 100, marks of 100.4 and 100.8 send nothing and 101 sends a map. A later fall to 99.99 sends another: it is 1% below 101.
  • 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 range percent below and above the mark, cut into buckets equal price bands. Every bucket is sent, empty ones included.
Create
Four buckets keep the sample short; the default is 50:
Delivery

State and delivery

  • Each subscription keeps its own state — per position on the wallet types, per direction on liquidationExposure, one reference price on liquidationMap. 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.
  • seq on 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 the seq of 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 on webhook-id.
  • Subscriptions are immutable. Delete and recreate one to change it; that also clears its state. A recreated wallet or liquidationExposure subscription can fire again on its first observation, and a recreated liquidationMap records a new reference price first.