Perfected FlowScript
OI Z-Score
OI Z-Score — Perfected Edition is indexed as 155_oi_z_score.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
offchart
Axis
true
Size
13.5 KB
Lines
439
Native Signal Candidates
8 source-level chart marker triggers extracted from guarded FlowScript v2 blocks.
Extreme Overlev
line 326:9
Trigger
(showShapes) && (extremeUp)
Value
z
Deps
extremeUp:var, showShapes:input
Extreme Capit
line 336:9
Trigger
(showShapes) && (extremeDown)
Value
z
Deps
extremeDown:var, showShapes:input
σ2 Overlev
line 346:9
Trigger
(showShapes) && (sigma2Up)
Value
z
Deps
showShapes:input, sigma2Up:var
σ2 Capit
line 356:9
Trigger
(showShapes) && (sigma2Down)
Value
z
Deps
showShapes:input, sigma2Down:var
Zero Cross Up
line 366:9
Trigger
(showShapes) && (crossUp)
Value
0
Deps
crossUp:var, showShapes:input
Zero Cross Down
line 376:9
Trigger
(showShapes) && (crossDown)
Value
0
Deps
crossDown:var, showShapes:input
OI Spike Up
line 386:9
Trigger
(showShapes) && (oiSpikeUp)
Value
band3Sigma
Deps
oiSpikeUp:var, showShapes:input
OI Spike Down
line 396:9
Trigger
(showShapes) && (oiSpikeDown)
Value
-band3Sigma
Deps
oiSpikeDown:var, showShapes:input
155_oi_z_score.flowscript
source path: kscripts/perfected/155_oi_z_score.flowscript · sha256:31b77e6fa4cac34732da0dd4a1fdf5581b342a59e361105dcf83f10c15e4cb2b
//@version=2
// ============================================================================
// OI Z-Score — Perfected Edition
// Author: arkutrades_1669 (@arkutrades_1669) | Enhanced by kScript_Perfection_Engineer
// Tags: ADVANCED, FLOW, #OI, #Z-Score, #regime, #leverage, #capitulation
//
// Production-quality Open Interest statistical oscillator that standardizes
// OI levels into a z-score regime indicator. Implements ±1/2/3σ bands with
// fill, regime detection (over-leveraged / capitulation / normal), color coding,
// shape markers, and static state tracking for duration context.
//
// Research papers underpinning this design:
// 1. Chen, Cuny & Haugen (1995), "Stock Volatility and the Levels of the
// Basis and Open Interest in Futures Contracts": establishes that OI
// levels contain information about future price volatility and market
// expectations. Higher OI correlates with greater information flow.
// 2. Yang Xu et al. (2021), "Price Volatility Characteristics of China's
// Soybean Futures Market": unexpected OI changes have larger impact on
// price volatility than expected changes. Z-score precisely captures
// these unexpected deviations from the rolling mean.
// 3. Zhao & Palomar (2018), "Mean-Reverting Portfolio With Budget Constraint":
// z = (X − μ) / σ with threshold entry/exit at ±1σ, ±2σ.
// 4. Brunnermeier & Pedersen (2009), "Market Liquidity and Funding Liquidity":
// liquidity spirals; when leverage is high, small shocks amplify into
// systemic crises. Extreme positive OI z-scores flag over-leveraged tops
// where cascade risk is elevated.
// 5. He & Manela (2022), "Fundamentals of Perpetual Futures": past-return
// momentum explains the futures-spot gap with R² > 50%. OI spikes in
// perps signal crowded positioning that drives funding deviations.
// ============================================================================
define(
title="OI Z-Score — Perfected Edition",
position="offchart",
axis=true
)
// ---------------------------------------------------------------------------
// 1. USER INPUTS — grouped with constraints
// ---------------------------------------------------------------------------
// --- Data Sources ---
var src = input(
name="src",
type="select",
defaultValue="BTCUSDT",
label="Symbol",
options=["BTCUSDT", "ETHUSDT", "SOLUSDT"],
group="Data Sources"
)
var exc = input(
name="exc",
type="select",
defaultValue="BINANCE_FUTURES",
label="Exchange",
options=["BINANCE_FUTURES", "BYBIT", "OKEX_SWAP", "DERIBIT"],
group="Data Sources"
)
// --- Computation ---
var zLen = input(
name="zLen",
type="number",
defaultValue=30,
label="Z Window",
constraints={min: 10, max: 100, step: 5},
group="Computation"
)
var smoothLen = input(
name="smoothLen",
type="number",
defaultValue=3,
label="Smoothing",
constraints={min: 1, max: 20, step: 1},
group="Computation"
)
var showOIChange = input(
name="showOIChange",
type="boolean",
defaultValue=true,
label="Show OI Change (bar-to-bar)",
group="Computation"
)
// --- Sigma Bands ---
var showBands = input(
name="showBands",
type="boolean",
defaultValue=true,
label="Show ±1/2/3σ Bands",
group="Sigma Bands"
)
var band1Sigma = input(
name="band1Sigma",
type="number",
defaultValue=1.0,
label="1σ Band",
constraints={min: 0.5, max: 2.0, step: 0.5},
group="Sigma Bands"
)
var band2Sigma = input(
name="band2Sigma",
type="number",
defaultValue=2.0,
label="2σ Band",
constraints={min: 1.0, max: 3.0, step: 0.5},
group="Sigma Bands"
)
var band3Sigma = input(
name="band3Sigma",
type="number",
defaultValue=3.0,
label="3σ Band",
constraints={min: 2.0, max: 4.0, step: 0.5},
group="Sigma Bands"
)
// --- Display ---
var showShapes = input(
name="showShapes",
type="boolean",
defaultValue=true,
label="Show Extreme Shapes",
group="Display"
)
var showMomentum = input(
name="showMomentum",
type="boolean",
defaultValue=true,
label="Show OI Change Momentum",
group="Display"
)
var showRegimeTable = input(
name="showRegimeTable",
type="boolean",
defaultValue=true,
label="Show Regime Table",
group="Display"
)
// --- Colors ---
var overlevColor = input(
name="overlevColor",
type="color",
defaultValue="#ef5350",
label="Over-Leveraged Color",
group="Colors"
)
var capitColor = input(
name="capitColor",
type="color",
defaultValue="#26a69a",
label="Capitulation Color",
group="Colors"
)
var neutralColor = input(
name="neutralColor",
type="color",
defaultValue="#78909c",
label="Neutral Color",
group="Colors"
)
var extremeColor = input(
name="extremeColor",
type="color",
defaultValue="#ffeb3b",
label="Extreme Color",
group="Colors"
)
var lineColor = input(
name="lineColor",
type="color",
defaultValue="#42a5f5",
label="Line Color",
group="Colors"
)
// ---------------------------------------------------------------------------
// 2. DATA SOURCES & NaN GUARD
// ---------------------------------------------------------------------------
timeseries oi = open_interest(symbol=src, exchange=exc)
if (isnan(oi.close[0])) {
return
}
// ---------------------------------------------------------------------------
// 3. Z-SCORE CALCULATION
// ---------------------------------------------------------------------------
// z = (OI − μ) / σ; guard against zero division.
timeseries oiMean = sma(oi.close, zLen)
timeseries oiStd = stdev(oi.close, zLen)
timeseries rawZ = (oi.close - oiMean) / math.max(oiStd, 0.0001)
timeseries z = ema(rawZ, smoothLen)
// Bar-to-bar OI change (momentum)
timeseries oiChange = oi.close - oi.close[1]
timeseries oiChangePct = oiMean > 0 ? (oiChange / oiMean) * 100.0 : 0.0
// ---------------------------------------------------------------------------
// 4. REGIME DETECTION
// ---------------------------------------------------------------------------
// Regime classification based on z position relative to sigma bands:
// Over-Leveraged (Hot): z > +1σ → unusually high OI = over-leveraged top risk
// Capitulation (Cold): z < −1σ → unusually low OI = capitulation / deleveraging
// Normal: |z| ≤ 1σ → typical positioning regime
var regimeOverlev = z > band1Sigma
var regimeCapit = z < -band1Sigma
var regimeNormal = !regimeOverlev && !regimeCapit
var regimeColor = regimeOverlev ? overlevColor : (regimeCapit ? capitColor : neutralColor)
// ---------------------------------------------------------------------------
// 5. STATIC STATE TRACKING — regime duration
// ---------------------------------------------------------------------------
static overlevBars = 0
static capitBars = 0
static normalBars = 0
static lastRegime = 0
if (regimeOverlev) {
overlevBars = overlevBars + 1
capitBars = 0
normalBars = 0
lastRegime = 1
} else if (regimeCapit) {
capitBars = capitBars + 1
overlevBars = 0
normalBars = 0
lastRegime = -1
} else {
normalBars = normalBars + 1
overlevBars = 0
capitBars = 0
lastRegime = 0
}
// ---------------------------------------------------------------------------
// 6. ALERT CONDITIONS
// ---------------------------------------------------------------------------
var extremeUp = z > band3Sigma && z[1] <= band3Sigma
var extremeDown = z < -band3Sigma && z[1] >= -band3Sigma
var sigma2Up = z > band2Sigma && z[1] <= band2Sigma
var sigma2Down = z < -band2Sigma && z[1] >= -band2Sigma
// Zero-line cross
var crossUp = z > 0 && z[1] <= 0
var crossDown = z < 0 && z[1] >= 0
// OI spike conditions
var oiSpikeUp = oiChange > 0 && oiChange > stdev(oiChange, zLen) * 2
var oiSpikeDown = oiChange < 0 && -oiChange > stdev(oiChange, zLen) * 2
// ---------------------------------------------------------------------------
// 7. PLOTTING
// ---------------------------------------------------------------------------
// --- Zero line ---
hline(value=0, color="#ffffff30", width=1)
// --- Sigma Bands (±1/2/3σ) with fill ---
if (showBands) {
hline(value=band1Sigma, color=transparency(overlevColor, 60), width=1)
hline(value=-band1Sigma, color=transparency(capitColor, 60), width=1)
hline(value=band2Sigma, color=transparency(overlevColor, 40), width=1)
hline(value=-band2Sigma, color=transparency(capitColor, 40), width=1)
hline(value=band3Sigma, color=transparency(extremeColor, 30), width=1)
hline(value=-band3Sigma, color=transparency(extremeColor, 30), width=1)
// Fill between ±1σ and ±2σ bands
plotLine(
value=[band2Sigma, band1Sigma],
width=1,
colors=[transparency(overlevColor, 15), transparency(overlevColor, 15)],
fill=true,
label=["2σ Band", "1σ Band"],
desc=["Upper 2σ band", "Upper 1σ band"]
)
plotLine(
value=[-band1Sigma, -band2Sigma],
width=1,
colors=[transparency(capitColor, 15), transparency(capitColor, 15)],
fill=true,
label=["1σ Band", "2σ Band"],
desc=["Lower 1σ band", "Lower 2σ band"]
)
}
// --- Z-Score Line (regime-colored) ---
plotLine(
value=z,
width=2,
colors=[regimeColor],
label=["OI Z"],
desc=["Smoothed Open Interest Z-Score (regime-colored)"]
)
// --- Z-Score Histogram (color-coded by regime) ---
var histColorIdx = regimeOverlev ? 0 : (regimeCapit ? 1 : 2)
plotBar(
value=z,
colors=[transparency(overlevColor, 60), transparency(capitColor, 60), transparency(neutralColor, 50)],
colorIndex=histColorIdx,
width=1,
label=["OI Z Hist"],
desc=["OI Z-Score histogram (color-coded by regime)"]
)
// --- OI Change Momentum ---
if (showMomentum && showOIChange) {
var changeBull = oiChange >= 0
plotBar(
value=oiChangePct,
colors=[transparency(capitColor, 40), transparency(overlevColor, 40)],
colorIndex=changeBull ? 0 : 1,
width=1,
label=["OI Change %"],
desc=["Bar-to-bar OI change as % of rolling mean"]
)
}
// --- Extreme Shape Markers ---
if (showShapes) {
if (extremeUp) {
plotShape(
value=z,
shape="triangledown",
colorIndex=extremeColor,
width=3,
label=["Extreme Overlev"],
desc=["OI Z-Score exceeded +3σ — over-leveraged top / cascade risk"]
)
}
if (extremeDown) {
plotShape(
value=z,
shape="triangleup",
colorIndex=extremeColor,
width=3,
label=["Extreme Capit"],
desc=["OI Z-Score fell below −3σ — capitulation / deleveraging bottom"]
)
}
if (sigma2Up) {
plotShape(
value=z,
shape="xcross",
colorIndex=overlevColor,
width=2,
label=["σ2 Overlev"],
desc=["OI Z-Score crossed above +2σ — over-leveraged warning"]
)
}
if (sigma2Down) {
plotShape(
value=z,
shape="xcross",
colorIndex=capitColor,
width=2,
label=["σ2 Capit"],
desc=["OI Z-Score crossed below −2σ — capitulation warning"]
)
}
if (crossUp) {
plotShape(
value=0,
shape="circle",
colorIndex=capitColor,
width=2,
label=["Zero Cross Up"],
desc=["OI Z-Score crossed above zero — positioning building"]
)
}
if (crossDown) {
plotShape(
value=0,
shape="circle",
colorIndex=overlevColor,
width=2,
label=["Zero Cross Down"],
desc=["OI Z-Score crossed below zero — positioning reducing"]
)
}
if (oiSpikeUp) {
plotShape(
value=band3Sigma,
shape="diamond",
colorIndex=overlevColor,
width=2,
label=["OI Spike Up"],
desc=["Unusually large OI increase — aggressive positioning build"]
)
}
if (oiSpikeDown) {
plotShape(
value=-band3Sigma,
shape="diamond",
colorIndex=capitColor,
width=2,
label=["OI Spike Down"],
desc=["Unusually large OI decrease — forced deleveraging / liquidation"]
)
}
}
// ---------------------------------------------------------------------------
// 8. REGIME TABLE (last bar only)
// ---------------------------------------------------------------------------
if (showRegimeTable && isLastBar) {
var regimeText = regimeOverlev ? "OVER-LEVERAGED" : (regimeCapit ? "CAPITULATION" : "NORMAL")
var regimeTextColor = regimeOverlev ? overlevColor : (regimeCapit ? capitColor : neutralColor)
plotTable(
data=[
["OI Z-Score — Perfected", regimeText],
["OI Z", z[0]],
["OI Level", oi.close[0]],
["OI Mean", oiMean[0]],
["OI Std", oiStd[0]],
["OI Change %", oiChangePct[0]],
["Overlev Bars", overlevBars],
["Capit Bars", capitBars],
["Normal Bars", normalBars]
],
position="top_right",
headerRow=true,
headerColumn=true,
textColor="#e2e8f0",
headerTextColor="#ffffff",
backgroundColor=transparency("#0f172a", 40),
headerBackgroundColor=transparency("#1e293b", 40),
borderColor=transparency("#334155", 40),
borderWidth=1,
fontSize=10,
cellPadding=4
)
}