Liquidation Safety
workflow.run_liquidation_safetyCalculate the liquidation price for an isolated-margin futures position with one flat maintenance margin rate (mmr, which you supply from your exchange's tier), unless you use the tiered mode described below. The default is isolated: it does not model a cross account. To get a cross-account figure pass walletBalance, otherMaintenanceMargin and otherUnrealizedPnl (any of them switches to cross, with size required), plus tiers for tiered maintenance margin; there is no separate marginMode parameter. The flat model is generic, for linear and inverse alike, not any one exchange's engine. By default the maintenance margin is taken on the position value at the liquidation price (the form Bybit, KuCoin and Hyperliquid document); mmBase "entry" takes it on the entry value (the form MEXC documents); liqFeeRate adds a liquidation fee to the rate (KuCoin). Optional tiered mode, for tiered maintenance margin and shared (cross) collateral after the Binance USD-M help page (linear) and the Bybit inverse and Binance COIN-M definitions (inverse, size in USD contracts, tier bands, cum, wallet and other-position fields all in the base coin): pass size (required there) and tiers (upTo, mmr, optional cum), optionally walletBalance, otherMaintenanceMargin, otherUnrealizedPnl. In that mode mmr is used only when tiers are left out, mmBase "entry" and liqFeeRate are refused, the last tier is open-ended, and the tier used is the one that holds the notional at the liquidation price (our choice, exchanges do not publish theirs); tier rows are supplied by you, never fetched here (for the current tiers of an exchange by symbol use workflow.run_liquidation_live), and the result then also carries tier {index, mmr, cum}. Without those fields it is the flat model: no tiers and no shared collateral, so it can differ from an exchange's own figure. Edge cases: entryPrice and leverage above zero; mmr 0 to 0.2 (default 0.005); liqFeeRate 0 to 0.05 (default 0, refused in tiered mode); tiered mode needs size, 1 to 50 tiers ascending by upTo, mmr 0 to 0.5 never lower than the previous tier, only the last tier may leave out upTo, and a cum that disagrees with the tier rates is an error; walletBalance above zero, otherOpenMaintenanceMargin 0 or more. Not covered: auto-deleveraging, partial liquidation, mark price versus last price, funding paid while open, and the exchange own engine, which may differ. Use when user asks "where will I get liquidated?" or "how close is my liq price?" with a margin rate or tier table given; when the user names an exchange and a symbol and gives no tier table, use workflow.run_liquidation_live instead. Returns: liqPrice (the price). liqPrice is null when the position cannot be liquidated: an inverse short whose margin covers any price rise (at 1x or less with the default mmBase; with mmBase "entry" only a little below 1x), or whose price would be more than 1e9 times the entry. Check for null before doing arithmetic on it. When mmr plus liqFeeRate is at least 1/leverage the position is already at or below its maintenance margin at entry: liqPrice is the entry price and liquidatedAtEntry is true.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"side": "<side>",
"entryPrice": "<entryPrice>",
"leverage": "<leverage>"
},
"name": "workflow.run_liquidation_safety"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mmr | No | Maintenance margin rate, default 0.005 (0.5%) | |
| side | Yes | Trade direction: "long" or "short" | |
| size | No | Position size: base units for linear, USD contracts for inverse. Needed for tiered mode (tiers, walletBalance and the other fields select it); ignored otherwise. | |
| tiers | No | Tiered mode (needs size): 1 to 50 maintenance margin tiers ascending by upTo (notional cap in quote for linear, in base coin for inverse, above 0; the last band is open-ended: an upTo given on the last tier is accepted and ignored); mmr 0 to 0.5 and not decreasing. cum = maintenance amount (Binance cum, Bybit mmDeduction); derived from the rates when omitted. | |
| mmBase | No | Value the maintenance margin is taken on: "liquidation" = position value at the liquidation price (default; Bybit, KuCoin, Hyperliquid), "entry" = entry value (MEXC). Refused in tiered mode. | |
| leverage | Yes | Leverage multiplier, e.g. 10 for 10x | |
| entryPrice | Yes | Entry price (positive) | |
| liqFeeRate | No | Liquidation fee as a fraction of position value, default 0, max 0.05; added to mmr (e.g. KuCoin 0.0006). Refused in tiered mode. | |
| contractType | No | linear = USDT-margined (default), inverse = coin-margined (e.g. Deribit/Bybit/MEXC BTC-settled perps). Tiers and shared collateral: both (inverse: size in USD, bands and balances in the base coin). | |
| walletBalance | No | Shared collateral (needs size): wallet balance backing the position. Default: the isolated initial margin, size x entry / leverage in quote for linear, size / entry / leverage in the base coin for inverse. | |
| otherUnrealizedPnl | No | Shared collateral: unrealized PnL of other positions (default 0, may be negative). | |
| otherMaintenanceMargin | No | Shared collateral (needs size): maintenance margin of other positions, 0 or more (default 0). |