MM Flow
FlowScripts

Perfected FlowScript

Liquidation Bands

Liquidation Bands — Perfected is indexed as 004_liquidation_bands.flowscript. The exact FlowScript is viewable here; chart observe and trading automation use the current mmflow chart/recipe signal proxy until FlowScript v2 transpilation is available.

This exact FlowScript uses the v2 source dialect. It is viewable and connected to the chart/automation proxy, but direct editor execution needs the FlowScript v2 transpiler.

Dialect

flowscript-v2

Compatibility

flowscript-v2-needs-transpile

Position

onchart

Axis

false

Size

18.4 KB

Lines

456

Native Signal Candidates

11 source-level chart marker triggers extracted from guarded FlowScript v2 blocks.

11/11 guarded

Near 5x Long Liq

line 330:9

Trigger

(showApproach) && (nearLong5)

Value

longLiq5

Deps

nearLong5:var, showApproach:input

Near 5x Short Liq

line 340:9

Trigger

(showApproach) && (nearShort5)

Value

shortLiq5

Deps

nearShort5:var, showApproach:input

Near 10x Long Liq

line 350:9

Trigger

(showApproach) && (nearLong10)

Value

longLiq10

Deps

nearLong10:var, showApproach:input

Near 10x Short Liq

line 360:9

Trigger

(showApproach) && (nearShort10)

Value

shortLiq10

Deps

nearShort10:var, showApproach:input

Near 20x Long Liq

line 370:9

Trigger

(showApproach) && (nearLong20)

Value

longLiq20

Deps

nearLong20:var, showApproach:input

Near 20x Short Liq

line 380:9

Trigger

(showApproach) && (nearShort20)

Value

shortLiq20

Deps

nearShort20:var, showApproach:input

Near 50x Long Liq

line 390:9

Trigger

(showApproach) && (nearLong50)

Value

longLiq50

Deps

nearLong50:var, showApproach:input

Near 50x Short Liq

line 400:9

Trigger

(showApproach) && (nearShort50)

Value

shortLiq50

Deps

nearShort50:var, showApproach:input

Near 100x Long Liq

line 410:9

Trigger

(showApproach) && (nearLong100)

Value

longLiq100

Deps

nearLong100:var, showApproach:input

Near 100x Short Liq

line 420:9

Trigger

(showApproach) && (nearShort100)

Value

shortLiq100

Deps

nearShort100:var, showApproach:input

CASCADE

line 435:5

Trigger

(showCascade && cascadeEvent)

Value

hi

Deps

cascadeEvent:var, showCascade:input

004_liquidation_bands.flowscript

source path: kscripts/perfected/004_liquidation_bands.flowscript · sha256:2ebe5bd3b0938685acfa0e7abe24e865ad6b34bd192e11f7a82adaf275fa51c0

hash verified
//@version=2
// Source: kiyotaka.ai/hub/kscript (original) — Perfected by kScript_Perfection_Engineer

// ============================================================================
// Liquidation Bands — Leverage-Based Failure Points & Cascade Detection
// Author: kiyotaka (@kiyotaka) — Perfected by kScript_Perfection_Engineer
// Tags: ADVANCED, FLOW, #liquidation, #leverage, #cascade, #futures
//
// Visualizes mathematical liquidation failure points for 5x, 10x, 20x, 50x,
// and 100x leveraged positions relative to current price. Supports both
// linear (USDT-margined) and inverse (coin-margined) perpetual futures.
// Includes color-coded danger levels, filled band zones, shape markers when
// price approaches liquidation levels, and a cascade detection system based
// on liquidation intensity exceeding 5% of open interest (Amberdata threshold).
//
// Research papers underpinning this design:
//  - Brunnermeier & Pedersen (2009), "Market Liquidity and Funding Liquidity"
//    (Rev. Financial Studies, 22(6)): liquidity spirals explain why
//    leveraged markets exhibit sudden, non-linear price moves when margin
//    thresholds are breached. Small shocks amplify into systemic crises.
//  - Bian et al. (2023), "Deleveraging Commonality" (J. Financial Economics):
//    forced selling from margin pressure propagates across assets; fire sales
//    create liquidity commonality. Systematic deleveraging measure validated
//    on margin trading data.
//  - Amberdata Research (2026), "Leverage & Liquidations: The $31B
//    Deleveraging": documents concrete cascade thresholds — liquidation
//    intensity > 5% of OI triggers forced-selling cascades; funding rates
//    > 15% APR signal overheating.
//  - "A Quantitative Analysis on BitMEX Perpetual Inverse Futures XBTUSD
//    Contract" (2020): liquidation as stopping-time problem; expected time
//    and probability of liquidation based on leverage and volatility.
//  - Adrian & Shin (2010), "Liquidity and Leverage" (J. Financial
//    Intermediation): leverage is procyclical — intermediaries expand leverage
//    during booms and reduce it during busts, amplifying business cycles.
// ============================================================================

define(
    title="Liquidation Bands — Perfected",
    position="onchart",
    axis=false
)

// ---------------------------------------------------------------------------
// User Inputs
// ---------------------------------------------------------------------------

// --- Display Group ---
var contractType = input(name="contractType", type="select", defaultValue="Linear (USDT)", label="Contract Type", options=["Linear (USDT)", "Inverse (Coin)"], group="Display")
var show5x = input(name="show5x", type="boolean", defaultValue=true, label="Show 5x Bands", group="Display")
var show10x = input(name="show10x", type="boolean", defaultValue=true, label="Show 10x Bands", group="Display")
var show20x = input(name="show20x", type="boolean", defaultValue=true, label="Show 20x Bands", group="Display")
var show50x = input(name="show50x", type="boolean", defaultValue=true, label="Show 50x Bands", group="Display")
var show100x = input(name="show100x", type="boolean", defaultValue=true, label="Show 100x Bands", group="Display")
var showFill = input(name="showFill", type="boolean", defaultValue=true, label="Show Band Fills", group="Display")
var showApproach = input(name="showApproach", type="boolean", defaultValue=true, label="Show Approach Shapes", group="Display")
var lineWidth = input(name="lineWidth", type="number", defaultValue=1, label="Line Width", constraints={min: 1, max: 4, step: 1}, group="Display")
var shapeSize = input(name="shapeSize", type="number", defaultValue=2, label="Shape Size", constraints={min: 1, max: 4, step: 1}, group="Display")
var approachPct = input(name="approachPct", type="number", defaultValue=2.0, label="Approach Distance (%)", constraints={min: 0.5, max: 10.0, step: 0.5}, group="Display")

// --- Cascade Detection Group ---
var showCascade = input(name="showCascade", type="boolean", defaultValue=true, label="Show Cascade Markers", group="Cascade Detection")
var cascadeThreshold = input(name="cascadeThreshold", type="number", defaultValue=5.0, label="Cascade Threshold (% of OI)", constraints={min: 1.0, max: 20.0, step: 0.5}, group="Cascade Detection")
var cascadeLookback = input(name="cascadeLookback", type="number", defaultValue=24, label="Cascade Lookback (bars)", constraints={min: 4, max: 100, step: 1}, group="Cascade Detection")

// --- Colors Group (danger level coding) ---
var col5x = input(name="col5x", type="color", defaultValue="#d32f2f", label="5x Color (Critical)", group="Colors")
var col10x = input(name="col10x", type="color", defaultValue="#ff6f00", label="10x Color (Severe)", group="Colors")
var col20x = input(name="col20x", type="color", defaultValue="#fbc02d", label="20x Color (Elevated)", group="Colors")
var col50x = input(name="col50x", type="color", defaultValue="#388e3c", label="50x Color (Moderate)", group="Colors")
var col100x = input(name="col100x", type="color", defaultValue="#1976d2", label="100x Color (Low)", group="Colors")
var cascadeColor = input(name="cascadeColor", type="color", defaultValue="#e91e63", label="Cascade Marker Color", group="Colors")

// ---------------------------------------------------------------------------
// Data Sources
// ---------------------------------------------------------------------------
timeseries bars = ohlcv(symbol=currentSymbol, exchange=currentExchange)
timeseries px = bars.close
timeseries hi = bars.high
timeseries lo = bars.low
timeseries oi = open_interest(symbol=currentSymbol, exchange=currentExchange)
timeseries liqs = source("liquidations", currentSymbol, currentExchange)

// isnan guard: prevent computation on incomplete data
if (isnan(px[0]) || isnan(hi[0]) || isnan(lo[0]) || isnan(oi[0])) {
    return
}

// ---------------------------------------------------------------------------
// Leverage-Based Liquidation Math
// ---------------------------------------------------------------------------
// For linear contracts (USDT-margined):  Liq = Price * (1 ± 1/L)
// For inverse contracts (coin-margined):  Liq = Price / (1 ± 1/L)
//   where (+) for long liquidation, (−) for short liquidation on inverse
//   and (−) for long, (+) for short on linear.

var isLinear = contractType == "Linear (USDT)"

// 5x leverage (most dangerous — tight margin)
timeseries longLiq5 = isLinear ? px * (1 - 1.0 / 5) : px / (1 + 1.0 / 5)
timeseries shortLiq5 = isLinear ? px * (1 + 1.0 / 5) : px / (1 - 1.0 / 5)

// 10x leverage
timeseries longLiq10 = isLinear ? px * (1 - 1.0 / 10) : px / (1 + 1.0 / 10)
timeseries shortLiq10 = isLinear ? px * (1 + 1.0 / 10) : px / (1 - 1.0 / 10)

// 20x leverage
timeseries longLiq20 = isLinear ? px * (1 - 1.0 / 20) : px / (1 + 1.0 / 20)
timeseries shortLiq20 = isLinear ? px * (1 + 1.0 / 20) : px / (1 - 1.0 / 20)

// 50x leverage
timeseries longLiq50 = isLinear ? px * (1 - 1.0 / 50) : px / (1 + 1.0 / 50)
timeseries shortLiq50 = isLinear ? px * (1 + 1.0 / 50) : px / (1 - 1.0 / 50)

// 100x leverage (widest band — least dangerous)
timeseries longLiq100 = isLinear ? px * (1 - 1.0 / 100) : px / (1 + 1.0 / 100)
timeseries shortLiq100 = isLinear ? px * (1 + 1.0 / 100) : px / (1 - 1.0 / 100)

// ---------------------------------------------------------------------------
// Cascade Detection — Liquidation Intensity vs. Open Interest
// ---------------------------------------------------------------------------
// Amberdata (2026): when liquidation intensity exceeds 5% of OI, forced
// selling triggers more forced selling. We compute rolling liquidation
// sum over cascadeLookback bars and flag when intensity > threshold.

timeseries longLiqVal = isnum(liqs.long) ? liqs.long : 0
timeseries shortLiqVal = isnum(liqs.short) ? liqs.short : 0
timeseries totalLiqVal = longLiqVal + shortLiqVal

timeseries liqSum = sum(totalLiqVal, cascadeLookback)
timeseries oiVal = oi.close > 0 ? oi.close : 1
timeseries liqIntensity = (liqSum / oiVal) * 100

var cascadeTrigger = liqIntensity >= cascadeThreshold

// --- STATIC STATE: Cascade Event Tracking ---
static lastCascadeBar = 0
static barCount = 0

if (!isLiveUpdate) {
    barCount = barCount + 1
    if (cascadeTrigger) {
        lastCascadeBar = barCount
    }
}

var cascadeEvent = lastCascadeBar == barCount

// ---------------------------------------------------------------------------
// Approach Detection — Shape Markers When Price Nears Liquidation
// ---------------------------------------------------------------------------
// Distance to liquidation as percentage of current price.

var distToLong5 = ((px - longLiq5) / px) * 100
var distToShort5 = ((shortLiq5 - px) / px) * 100
var distToLong10 = ((px - longLiq10) / px) * 100
var distToShort10 = ((shortLiq10 - px) / px) * 100
var distToLong20 = ((px - longLiq20) / px) * 100
var distToShort20 = ((shortLiq20 - px) / px) * 100
var distToLong50 = ((px - longLiq50) / px) * 100
var distToShort50 = ((shortLiq50 - px) / px) * 100
var distToLong100 = ((px - longLiq100) / px) * 100
var distToShort100 = ((shortLiq100 - px) / px) * 100

var nearLong5 = distToLong5 <= approachPct && distToLong5 > 0
var nearShort5 = distToShort5 <= approachPct && distToShort5 > 0
var nearLong10 = distToLong10 <= approachPct && distToLong10 > 0
var nearShort10 = distToShort10 <= approachPct && distToShort10 > 0
var nearLong20 = distToLong20 <= approachPct && distToLong20 > 0
var nearShort20 = distToShort20 <= approachPct && distToShort20 > 0
var nearLong50 = distToLong50 <= approachPct && distToLong50 > 0
var nearShort50 = distToShort50 <= approachPct && distToShort50 > 0
var nearLong100 = distToLong100 <= approachPct && distToLong100 > 0
var nearShort100 = distToShort100 <= approachPct && distToShort100 > 0

// ---------------------------------------------------------------------------
// Plotting: 5x Bands (Critical — Red)
// ---------------------------------------------------------------------------
if (show5x) {
    if (showFill) {
        plotLine(
            value=[longLiq5, shortLiq5],
            width=1,
            colors=[opacity(col5x, 12), opacity(col5x, 12)],
            fill=opacity(col5x, 12),
            label=["5x Long Zone", "5x Short Zone"],
            desc=["5x long liquidation band", "5x short liquidation band"]
        )
    }
    plotLine(
        value=longLiq5,
        width=lineWidth + 1,
        colors=[col5x],
        label=["Long Liq 5x"],
        desc=["Long liquidation level at 5x leverage (critical)"]
    )
    plotLine(
        value=shortLiq5,
        width=lineWidth + 1,
        colors=[col5x],
        label=["Short Liq 5x"],
        desc=["Short liquidation level at 5x leverage (critical)"]
    )
}

// ---------------------------------------------------------------------------
// Plotting: 10x Bands (Severe — Orange)
// ---------------------------------------------------------------------------
if (show10x) {
    if (showFill) {
        plotLine(
            value=[longLiq10, shortLiq10],
            width=1,
            colors=[opacity(col10x, 10), opacity(col10x, 10)],
            fill=opacity(col10x, 10),
            label=["10x Long Zone", "10x Short Zone"],
            desc=["10x long liquidation band", "10x short liquidation band"]
        )
    }
    plotLine(
        value=longLiq10,
        width=lineWidth,
        colors=[col10x],
        label=["Long Liq 10x"],
        desc=["Long liquidation level at 10x leverage (severe)"]
    )
    plotLine(
        value=shortLiq10,
        width=lineWidth,
        colors=[col10x],
        label=["Short Liq 10x"],
        desc=["Short liquidation level at 10x leverage (severe)"]
    )
}

// ---------------------------------------------------------------------------
// Plotting: 20x Bands (Elevated — Yellow)
// ---------------------------------------------------------------------------
if (show20x) {
    if (showFill) {
        plotLine(
            value=[longLiq20, shortLiq20],
            width=1,
            colors=[opacity(col20x, 8), opacity(col20x, 8)],
            fill=opacity(col20x, 8),
            label=["20x Long Zone", "20x Short Zone"],
            desc=["20x long liquidation band", "20x short liquidation band"]
        )
    }
    plotLine(
        value=longLiq20,
        width=lineWidth,
        colors=[col20x],
        label=["Long Liq 20x"],
        desc=["Long liquidation level at 20x leverage (elevated)"]
    )
    plotLine(
        value=shortLiq20,
        width=lineWidth,
        colors=[col20x],
        label=["Short Liq 20x"],
        desc=["Short liquidation level at 20x leverage (elevated)"]
    )
}

// ---------------------------------------------------------------------------
// Plotting: 50x Bands (Moderate — Green)
// ---------------------------------------------------------------------------
if (show50x) {
    if (showFill) {
        plotLine(
            value=[longLiq50, shortLiq50],
            width=1,
            colors=[opacity(col50x, 6), opacity(col50x, 6)],
            fill=opacity(col50x, 6),
            label=["50x Long Zone", "50x Short Zone"],
            desc=["50x long liquidation band", "50x short liquidation band"]
        )
    }
    plotLine(
        value=longLiq50,
        width=lineWidth,
        colors=[col50x],
        label=["Long Liq 50x"],
        desc=["Long liquidation level at 50x leverage (moderate)"]
    )
    plotLine(
        value=shortLiq50,
        width=lineWidth,
        colors=[col50x],
        label=["Short Liq 50x"],
        desc=["Short liquidation level at 50x leverage (moderate)"]
    )
}

// ---------------------------------------------------------------------------
// Plotting: 100x Bands (Low — Blue)
// ---------------------------------------------------------------------------
if (show100x) {
    if (showFill) {
        plotLine(
            value=[longLiq100, shortLiq100],
            width=1,
            colors=[opacity(col100x, 5), opacity(col100x, 5)],
            fill=opacity(col100x, 5),
            label=["100x Long Zone", "100x Short Zone"],
            desc=["100x long liquidation band", "100x short liquidation band"]
        )
    }
    plotLine(
        value=longLiq100,
        width=lineWidth,
        colors=[col100x],
        label=["Long Liq 100x"],
        desc=["Long liquidation level at 100x leverage (low)"]
    )
    plotLine(
        value=shortLiq100,
        width=lineWidth,
        colors=[col100x],
        label=["Short Liq 100x"],
        desc=["Short liquidation level at 100x leverage (low)"]
    )
}

// ---------------------------------------------------------------------------
// Plotting: Approach Shape Markers
// ---------------------------------------------------------------------------
if (showApproach) {
    if (nearLong5) {
        plotShape(
            value=longLiq5,
            shape="triangleup",
            colorIndex=col5x,
            width=shapeSize,
            label=["Near 5x Long Liq"],
            desc=["Price approaching 5x long liquidation level (critical)"]
        )
    }
    if (nearShort5) {
        plotShape(
            value=shortLiq5,
            shape="triangledown",
            colorIndex=col5x,
            width=shapeSize,
            label=["Near 5x Short Liq"],
            desc=["Price approaching 5x short liquidation level (critical)"]
        )
    }
    if (nearLong10) {
        plotShape(
            value=longLiq10,
            shape="triangleup",
            colorIndex=col10x,
            width=shapeSize,
            label=["Near 10x Long Liq"],
            desc=["Price approaching 10x long liquidation level (severe)"]
        )
    }
    if (nearShort10) {
        plotShape(
            value=shortLiq10,
            shape="triangledown",
            colorIndex=col10x,
            width=shapeSize,
            label=["Near 10x Short Liq"],
            desc=["Price approaching 10x short liquidation level (severe)"]
        )
    }
    if (nearLong20) {
        plotShape(
            value=longLiq20,
            shape="triangleup",
            colorIndex=col20x,
            width=shapeSize,
            label=["Near 20x Long Liq"],
            desc=["Price approaching 20x long liquidation level (elevated)"]
        )
    }
    if (nearShort20) {
        plotShape(
            value=shortLiq20,
            shape="triangledown",
            colorIndex=col20x,
            width=shapeSize,
            label=["Near 20x Short Liq"],
            desc=["Price approaching 20x short liquidation level (elevated)"]
        )
    }
    if (nearLong50) {
        plotShape(
            value=longLiq50,
            shape="triangleup",
            colorIndex=col50x,
            width=shapeSize,
            label=["Near 50x Long Liq"],
            desc=["Price approaching 50x long liquidation level (moderate)"]
        )
    }
    if (nearShort50) {
        plotShape(
            value=shortLiq50,
            shape="triangledown",
            colorIndex=col50x,
            width=shapeSize,
            label=["Near 50x Short Liq"],
            desc=["Price approaching 50x short liquidation level (moderate)"]
        )
    }
    if (nearLong100) {
        plotShape(
            value=longLiq100,
            shape="triangleup",
            colorIndex=col100x,
            width=shapeSize,
            label=["Near 100x Long Liq"],
            desc=["Price approaching 100x long liquidation level (low)"]
        )
    }
    if (nearShort100) {
        plotShape(
            value=shortLiq100,
            shape="triangledown",
            colorIndex=col100x,
            width=shapeSize,
            label=["Near 100x Short Liq"],
            desc=["Price approaching 100x short liquidation level (low)"]
        )
    }
}

// ---------------------------------------------------------------------------
// Plotting: Cascade Markers
// ---------------------------------------------------------------------------
if (showCascade && cascadeEvent) {
    plotShape(
        value=hi,
        shape="rectangle",
        colorIndex=cascadeColor,
        width=6,
        label=["CASCADE"],
        desc=["Liquidation cascade detected: intensity exceeds " + cascadeThreshold + "% of OI (Amberdata threshold)"]
    )
}

// ---------------------------------------------------------------------------
// Plotting: Liquidation Intensity (plotBar on secondary axis)
// ---------------------------------------------------------------------------
if (showCascade) {
    plotBar(
        value=liqIntensity,
        colors=[liqIntensity >= cascadeThreshold ? cascadeColor : opacity(cascadeColor, 40)],
        label=["Liq Intensity (% OI)"],
        desc=["Rolling liquidation sum as % of open interest over " + cascadeLookback + " bars"]
    )
}