Perfected FlowScript
Disbalance Coinbase
Disbalance Coinbase — Perfected Edition is indexed as 253_disbalance_coinbase.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
19.8 KB
Lines
449
Native Signal Candidates
6 source-level chart marker triggers extracted from guarded FlowScript v2 blocks.
Bull Regime
line 356:9
Trigger
(showShapes) && (crossUp)
Value
smoothedComposite
Deps
crossUp:var, showShapes:input
Bear Regime
line 366:9
Trigger
(showShapes) && (crossDn)
Value
smoothedComposite
Deps
crossDn:var, showShapes:input
Extreme Bid
line 376:9
Trigger
(showShapes) && (extremeUp)
Value
smoothedComposite
Deps
extremeUp:var, showShapes:input
Extreme Ask
line 386:9
Trigger
(showShapes) && (extremeDn)
Value
smoothedComposite
Deps
extremeDn:var, showShapes:input
Z-Extreme Bid
line 396:9
Trigger
(showShapes) && (zUp)
Value
smoothedComposite
Deps
showShapes:input, zUp:var
Z-Extreme Ask
line 406:9
Trigger
(showShapes) && (zDn)
Value
smoothedComposite
Deps
showShapes:input, zDn:var
253_disbalance_coinbase.flowscript
source path: kscripts/perfected/253_disbalance_coinbase.flowscript · sha256:e8d2dc76b27dee812936ad30b3f403ab4ca56d3a04e8a9bf557e1bffa20b962b
//@version=2
// ============================================================================
// Disbalance Coinbase — Perfected Edition
// Author: M (@Muhammad Dinaev) | Enhanced by kScript Perfection Engineer
// Tags: CORE, FLOW, #orderbook, #OBI, #disbalance, #coinbase, #microstructure
//
// Production-quality multi-depth orderbook imbalance indicator for Coinbase
// BTCUSDT spot. Implements proper depth-weighted OBI computation, z-score
// normalization, regime detection, and comprehensive fill/shape visualization.
//
// FORMULA FOUNDATION:
// 1. Order Book Imbalance (OBI): OBI = (BidVol − AskVol) / (BidVol + AskVol) ∈ [−1, +1]
// per Order Book Filtration and Directional Signal Extraction (2025).
// 2. Depth-Weighted Composite OBI: Σ w_i × OBI_i / Σ w_i where w_i = decay^(i−1)
// per Xu, Gould & Howison (2019), multi-level OFI with decaying weights.
// 3. Regime Segmentation: Sell-heavy (−1, −1/3), Neutral (−1/3, +1/3),
// Buy-heavy (+1/3, +1) per Cartea, Donnelly & Jaimungal (2018).
// 4. Z-Score Normalization: (OBI − μ_OBI) / σ_OBI over rolling window to flag
// statistically extreme imbalances per Poterba & Summers (1988) mean-reversion.
//
// CRITICAL BUG FIX: The original script used total-depth scaling estimates
// (bidsTotal * 0.30) which completely discards the actual orderbook structure
// at each depth level. This version queries the orderbook API at each specific
// depth percentage, preserving true microstructure information.
//
// RESEARCH BASIS:
// • Cont, Kukanov & Stoikov (2014), JFEC 12(1):47-88. OFI = Σ(E_i × ΔP_i);
// slope of price impact ∝ 1/depth. Multi-depth OBI captures this relationship.
// • Xu, Gould & Howison (2019), arXiv:1907.06230. Multi-level OFI with decaying
// weights significantly improves short-horizon prediction vs. top-of-book alone.
// • Cartea, Donnelly & Jaimungal (2018), Appl. Math. Finance 25(1):1-35.
// Three-regime segmentation: Sell-heavy (−1,−1/3), Neutral (−1/3,1/3),
// Buy-heavy (1/3,1). Positive changes preceded by buy-heavy books.
// • Gould & Bonart (2016), Market Microstructure & Liquidity 2(1):1650006.
// Queue imbalance as next-tick direction predictor; logistic regression
// showed significant classification improvement.
// • Aleti & Mizrach (2021), J. Futures Markets 41:194-225. BTC spot market
// microstructure across exchanges; median trade sizes < $1,300, spreads
// averaging 0.0298%. Coinbase depth provides key microstructure data.
// ============================================================================
define(
title="Disbalance Coinbase — Perfected Edition",
position="offchart",
axis=true
)
// -----------------------------------------------------------------------------
// 1. USER INPUTS — grouped with constraints
// -----------------------------------------------------------------------------
// --- Depth Configuration ---
var depth1 = input(name="depth1", type="number", defaultValue=1.0, label="Depth Band 1 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")
var depth2 = input(name="depth2", type="number", defaultValue=3.0, label="Depth Band 2 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")
var depth3 = input(name="depth3", type="number", defaultValue=5.0, label="Depth Band 3 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")
var depth4 = input(name="depth4", type="number", defaultValue=10.0, label="Depth Band 4 (%)", constraints={min: 0.1, max: 50.0, step: 0.1}, group="Depth")
var useDepthWeighting = input(name="useDepthWeighting", type="boolean", defaultValue=true, label="Use Depth-Decaying Weights", group="Depth")
var weightDecay = input(name="weightDecay", type="number", defaultValue=0.75, label="Weight Decay Factor", constraints={min: 0.0, max: 1.0, step: 0.05}, group="Depth")
// --- Smoothing ---
var smoothLen = input(name="smoothLen", type="number", defaultValue=5, label="EMA Smoothing Length", constraints={min: 1, max: 50, step: 1}, group="Smoothing")
var smoothComposite = input(name="smoothComposite", type="boolean", defaultValue=true, label="Smooth Composite OBI", group="Smoothing")
// --- Z-Score ---
var useZScore = input(name="useZScore", type="boolean", defaultValue=true, label="Enable Z-Score Normalization", group="Z-Score")
var zScoreWindow = input(name="zScoreWindow", type="number", defaultValue=50, label="Z-Score Rolling Window", constraints={min: 20, max: 200, step: 1}, group="Z-Score")
// --- Thresholds & Regime ---
var bullThresh = input(name="bullThresh", type="number", defaultValue=33.0, label="Bullish Regime Threshold (%)", constraints={min: 10.0, max: 90.0, step: 1.0}, group="Thresholds")
var bearThresh = input(name="bearThresh", type="number", defaultValue=-33.0, label="Bearish Regime Threshold (%)", constraints={min: -90.0, max: -10.0, step: 1.0}, group="Thresholds")
var extremeThresh = input(name="extremeThresh", type="number", defaultValue=66.0, label="Extreme Imbalance Threshold (%)", constraints={min: 50.0, max: 95.0, step: 1.0}, group="Thresholds")
// --- Display ---
var showGuides = input(name="showGuides", type="boolean", defaultValue=true, label="Show Guide Lines", group="Display")
var showRawBars = input(name="showRawBars", type="boolean", defaultValue=true, label="Show Raw OBI Histogram", group="Display")
var showShapes = input(name="showShapes", type="boolean", defaultValue=true, label="Show Regime Shapes", group="Display")
var showComposite = input(name="showComposite", type="boolean", defaultValue=true, label="Show Composite Line", group="Display")
var showIndividual = input(name="showIndividual", type="boolean", defaultValue=false, label="Show Individual Depth Lines", group="Display")
var showZScore = input(name="showZScore", type="boolean", defaultValue=true, label="Show Z-Score Line", group="Display")
var showBidAskRatio = input(name="showBidAskRatio", type="boolean", defaultValue=false, label="Show Bid/Ask Ratio (1% depth)", group="Display")
// --- Colors ---
var bidColor = input(name="bidColor", type="color", defaultValue="#26a69a", label="Bid-Dominant Color", group="Colors")
var askColor = input(name="askColor", type="color", defaultValue="#ef5350", label="Ask-Dominant Color", group="Colors")
var neutralColor = input(name="neutralColor", type="color", defaultValue="#9e9e9e", label="Neutral Color", group="Colors")
var extremeBidColor = input(name="extremeBidColor", type="color", defaultValue="#00e676", label="Extreme Bid Color", group="Colors")
var extremeAskColor = input(name="extremeAskColor", type="color", defaultValue="#ff1744", label="Extreme Ask Color", group="Colors")
// -----------------------------------------------------------------------------
// 2. DATA SOURCES & NaN GUARD
// -----------------------------------------------------------------------------
timeseries priceBars = ohlcv(symbol=currentSymbol, exchange=currentExchange)
timeseries px = priceBars.close
// Coinbase orderbook source
timeseries book = source("orderbook", "BTCUSDT", "COINBASE")
// NaN guard — prevent execution before data is loaded
if (isnan(px[0])) {
return
}
// -----------------------------------------------------------------------------
// 3. ORDER BOOK AGGREGATION (proper API usage per depth level)
// -----------------------------------------------------------------------------
// CRITICAL FIX: The original script used total-depth estimates (bidsTotal * 0.30)
// which discard true microstructure. We now query each depth band directly.
// The kScript API accepts depth as a float percentage (e.g., 1.0 = 1%).
var bids1 = sumBids(book, depth1)
var asks1 = sumAsks(book, depth1)
var bids2 = sumBids(book, depth2)
var asks2 = sumAsks(book, depth2)
var bids3 = sumBids(book, depth3)
var asks3 = sumAsks(book, depth3)
var bids4 = sumBids(book, depth4)
var asks4 = sumAsks(book, depth4)
// Book availability check — prevents NaN/undefined propagation
var bookAvailable = !isnan(bids1) && !isnan(asks1) && bids1 > 0 && asks1 > 0 &&
!isnan(bids2) && !isnan(asks2) && bids2 > 0 && asks2 > 0 &&
!isnan(bids3) && !isnan(asks3) && bids3 > 0 && asks3 > 0 &&
!isnan(bids4) && !isnan(asks4) && bids4 > 0 && asks4 > 0
// -----------------------------------------------------------------------------
// 4. OBI COMPUTATION WITH ZERO-DIVISION GUARDS
// -----------------------------------------------------------------------------
// OBI = (Bid − Ask) / (Bid + Ask) ∈ [−1, +1]
// Per Order Book Filtration and Directional Signal Extraction (2025)
var denom1 = bids1 + asks1
var denom2 = bids2 + asks2
var denom3 = bids3 + asks3
var denom4 = bids4 + asks4
var obi1 = bookAvailable && denom1 > 0 ? (bids1 - asks1) / denom1 * 100.0 : 0.0
var obi2 = bookAvailable && denom2 > 0 ? (bids2 - asks2) / denom2 * 100.0 : 0.0
var obi3 = bookAvailable && denom3 > 0 ? (bids3 - asks3) / denom3 * 100.0 : 0.0
var obi4 = bookAvailable && denom4 > 0 ? (bids4 - asks4) / denom4 * 100.0 : 0.0
// Bid/Ask ratio for 1% depth (diagnostic per Gould & Bonart 2016)
var ratio1 = bookAvailable && asks1 > 0 ? bids1 / asks1 : 1.0
// -----------------------------------------------------------------------------
// 5. DEPTH-WEIGHTED COMPOSITE OBI (Xu, Gould & Howison 2019)
// -----------------------------------------------------------------------------
// Multi-level OFI with geometrically decaying weights.
// w_i = decay^(i−1) for i = 1,2,3,4.
// Composite = Σ w_i × OBI_i / Σ w_i.
var w1 = 1.0
var w2 = useDepthWeighting ? weightDecay : 1.0
var w3 = useDepthWeighting ? weightDecay * weightDecay : 1.0
var w4 = useDepthWeighting ? weightDecay * weightDecay * weightDecay : 1.0
var wSum = w1 + w2 + w3 + w4
var compositeOBI = wSum > 0 ? (w1 * obi1 + w2 * obi2 + w3 * obi3 + w4 * obi4) / wSum : 0.0
// -----------------------------------------------------------------------------
// 6. Z-SCORE NORMALIZATION
// -----------------------------------------------------------------------------
// (OBI − μ_OBI) / σ_OBI over rolling window to flag statistically extreme
// imbalances. Readings beyond ±2σ are rare (~5% of observations) and likely
// to revert per mean-reversion literature.
timeseries obiMean = sma(source=compositeOBI, period=zScoreWindow)
timeseries obiStd = stddev(source=compositeOBI, period=zScoreWindow)
timeseries obiZScore = obiStd > 0 ? (compositeOBI - obiMean) / obiStd : 0.0
// Z-score extreme flags
var zExtremeBid = obiZScore >= 2.0
var zExtremeAsk = obiZScore <= -2.0
// -----------------------------------------------------------------------------
// 7. SMOOTHING (EMA per Cont et al. 2014 noise-reduction)
// -----------------------------------------------------------------------------
var smoothed1 = ema(obi1, smoothLen)
var smoothed2 = ema(obi2, smoothLen)
var smoothed3 = ema(obi3, smoothLen)
var smoothed4 = ema(obi4, smoothLen)
var smoothedComposite = smoothComposite ? ema(compositeOBI, smoothLen) : compositeOBI
var smoothedZScore = ema(obiZScore, smoothLen)
// -----------------------------------------------------------------------------
// 8. REGIME DETECTION (Cartea, Donnelly & Jaimungal 2018 three-segment model)
// -----------------------------------------------------------------------------
// Segmented into three regimes:
// Sell-heavy: OBI ≤ bearThresh
// Neutral: bearThresh < OBI < bullThresh
// Buy-heavy: OBI ≥ bullThresh
// Positive changes preceded by buy-heavy books; negative by sell-heavy.
var regime = 0 // 0 = neutral, 1 = bull, -1 = bear
var extremeRegime = 0 // 0 = normal, 1 = extreme bull, -1 = extreme bear
if (smoothedComposite >= bullThresh) {
regime = 1
} else if (smoothedComposite <= bearThresh) {
regime = -1
}
if (smoothedComposite >= extremeThresh) {
extremeRegime = 1
} else if (smoothedComposite <= -extremeThresh) {
extremeRegime = -1
}
// Regime color for composite line
var regimeColor = regime == 1 ? bidColor : (regime == -1 ? askColor : neutralColor)
// -----------------------------------------------------------------------------
// 9. STATIC STATE TRACKING (Session-level persistence)
// -----------------------------------------------------------------------------
// Tracks regime transitions, session extremes, and extreme-event counts.
static lastRegime = 0
static regimeChangeCount = 0
static sessionHighOBI = -999999.0
static sessionLowOBI = 999999.0
static extremeBidCount = 0
static extremeAskCount = 0
static lastBarIndex = 0
var currentBarIndex = bar_index[0]
if (!isnan(currentBarIndex) && currentBarIndex != lastBarIndex) {
lastBarIndex = currentBarIndex
if (compositeOBI > sessionHighOBI) {
sessionHighOBI = compositeOBI
}
if (compositeOBI < sessionLowOBI) {
sessionLowOBI = compositeOBI
}
if (lastRegime != regime) {
lastRegime = regime
regimeChangeCount = regimeChangeCount + 1
}
if (extremeRegime == 1) {
extremeBidCount = extremeBidCount + 1
} else if (extremeRegime == -1) {
extremeAskCount = extremeAskCount + 1
}
}
// -----------------------------------------------------------------------------
// 10. PLOTS — Multiple Visualization Types (Line, Bar, Shape, Fill, HLine)
// -----------------------------------------------------------------------------
// Horizontal guide lines
hline(value=0, color="#ffffff30", width=1)
if (showGuides) {
hline(value=bullThresh, color=opacity(bidColor, 30), width=1)
hline(value=bearThresh, color=opacity(askColor, 30), width=1)
hline(value=extremeThresh, color=opacity(extremeBidColor, 20), width=1)
hline(value=-extremeThresh, color=opacity(extremeAskColor, 20), width=1)
}
// Raw composite OBI as histogram bars
if (showRawBars) {
plotBar(
value=compositeOBI,
colors=[bidColor, askColor, neutralColor],
colorIndex=regime == 1 ? 0 : (regime == -1 ? 1 : 2),
width=1,
label=["Composite OBI Raw"],
desc=["Depth-weighted composite OBI histogram (positive=bid, negative=ask)"]
)
}
// Smoothed composite line with fill area
if (showComposite) {
plotLine(
value=smoothedComposite,
width=2,
colors=[regimeColor],
label=["Composite OBI"],
desc=["Depth-weighted composite OBI (EMA-smoothed). Regime: bull/bear/neutral."],
fill=true
)
}
// Z-Score line (secondary, thinner)
if (showZScore) {
plotLine(
value=smoothedZScore * 20, // Scale to roughly match OBI range for visual alignment
width=1,
colors=[extremeBidColor, extremeAskColor, neutralColor],
colorIndex=smoothedZScore > 1.0 ? 0 : (smoothedZScore < -1.0 ? 1 : 2),
label=["OBI Z-Score (×20)"],
desc=["Z-score of composite OBI (scaled ×20 for visual alignment with OBI axis)"]
)
hline(value=40, color=opacity(extremeBidColor, 20), width=1)
hline(value=-40, color=opacity(extremeAskColor, 20), width=1)
}
// Individual depth lines (optional)
if (showIndividual) {
plotLine(
value=smoothed1,
width=1,
colors=[opacity(bidColor, 50)],
label=["OBI 1%"],
desc=["Order Book Imbalance at 1% depth (shallow book, top-of-book)"]
)
plotLine(
value=smoothed2,
width=1,
colors=[opacity(bidColor, 40)],
label=["OBI 3%"],
desc=["Order Book Imbalance at 3% depth (near-term liquidity)"]
)
plotLine(
value=smoothed3,
width=1,
colors=[opacity(askColor, 40)],
label=["OBI 5%"],
desc=["Order Book Imbalance at 5% depth (medium-term absorption)"]
)
plotLine(
value=smoothed4,
width=1,
colors=[opacity(askColor, 50)],
label=["OBI 10%"],
desc=["Order Book Imbalance at 10% depth (deep book, structural level)"]
)
}
// Bid/Ask ratio line (1% depth diagnostic)
if (showBidAskRatio) {
var ratioPct = (ratio1 - 1.0) * 100.0
plotLine(
value=ratioPct,
width=1,
colors=[bidColor, askColor, neutralColor],
colorIndex=ratioPct > 5.0 ? 0 : (ratioPct < -5.0 ? 1 : 2),
label=["Bid/Ask Ratio 1%"],
desc=["Bid/Ask ratio at 1% depth, centered at 0 (positive = bid heavy)"]
)
}
// Regime transition shapes
if (showShapes) {
var crossUp = smoothedComposite >= bullThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] < bullThresh
var crossDn = smoothedComposite <= bearThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] > bearThresh
var extremeUp = smoothedComposite >= extremeThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] < extremeThresh
var extremeDn = smoothedComposite <= -extremeThresh && !isnan(smoothedComposite[1]) && smoothedComposite[1] > -extremeThresh
var zUp = zExtremeBid && !isnan(obiZScore[1]) && obiZScore[1] < 2.0
var zDn = zExtremeAsk && !isnan(obiZScore[1]) && obiZScore[1] > -2.0
if (crossUp) {
plotShape(
value=smoothedComposite,
shape="triangleup",
color=extremeBidColor,
width=3,
label=["Bull Regime"],
desc=["Composite OBI crossed into bullish regime (buy-heavy)"]
)
}
if (crossDn) {
plotShape(
value=smoothedComposite,
shape="triangledown",
color=extremeAskColor,
width=3,
label=["Bear Regime"],
desc=["Composite OBI crossed into bearish regime (sell-heavy)"]
)
}
if (extremeUp) {
plotShape(
value=smoothedComposite,
shape="diamond",
color=extremeBidColor,
width=4,
label=["Extreme Bid"],
desc=["Extreme bid pressure detected — deep book buy-heavy imbalance"]
)
}
if (extremeDn) {
plotShape(
value=smoothedComposite,
shape="diamond",
color=extremeAskColor,
width=4,
label=["Extreme Ask"],
desc=["Extreme ask pressure detected — deep book sell-heavy imbalance"]
)
}
if (zUp) {
plotShape(
value=smoothedComposite,
shape="xcross",
color=extremeBidColor,
width=2,
label=["Z-Extreme Bid"],
desc=["Z-score extreme bid imbalance (≥+2σ) — statistically rare, mean-reversion candidate"]
)
}
if (zDn) {
plotShape(
value=smoothedComposite,
shape="xcross",
color=extremeAskColor,
width=2,
label=["Z-Extreme Ask"],
desc=["Z-score extreme ask imbalance (≤−2σ) — statistically rare, mean-reversion candidate"]
)
}
}
// -----------------------------------------------------------------------------
// 11. REGIME TABLE (last bar only)
// -----------------------------------------------------------------------------
if (isLastBar) {
var regimeText = regime == 1 ? "BUY-HEAVY" : (regime == -1 ? "SELL-HEAVY" : "NEUTRAL")
var regimeTextColor = regime == 1 ? bidColor : (regime == -1 ? askColor : neutralColor)
var extremeText = extremeRegime == 1 ? "EXTREME BID" : (extremeRegime == -1 ? "EXTREME ASK" : "NORMAL")
plotTable(
data=[
["Disbalance Coinbase — Perfected", regimeText + " | " + extremeText],
["Composite OBI", math.round(smoothedComposite[0] * 100) / 100],
["OBI Z-Score", math.round(obiZScore[0] * 100) / 100],
["Session High OBI", math.round(sessionHighOBI * 100) / 100],
["Session Low OBI", math.round(sessionLowOBI * 100) / 100],
["Regime Changes", regimeChangeCount],
["Extreme Bid Events", extremeBidCount],
["Extreme Ask Events", extremeAskCount]
],
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
)
}