Squeeze Breakout

Description

A breakout means something different depending on whether volatility was compressed before it. Breakouts from a tight base tend to continue; breakouts from an already expanded band tend to revert. The distinction is not price, it is relative band width. This package measures width as (upper - lower) / mid, which is dimensionless. That single choice is why the same threshold is meaningful on a 60k asset and a 0.6 asset, and why you can carry one calibrated number across symbols instead of one per instrument. The signal itself is a band cross, not merely price outside the band, so the decision fires once per event. WHEN TO USE THIS • An agent must tag a breakout as compression-driven or not. • You want a breakout rule whose threshold transfers across price levels without re-tuning. • You need to explain why an absolute-width squeeze threshold is a scaling bug. Weak in strongly trending markets: the band is dragged upward by the trend and the compression state rarely registers. WHAT THIS PACKAGE DELIBERATELY DOES NOT CONTAIN This is a framework release, not the tuned production build. Specifically: • No position sizing, stop, or target. A breakout needs all three and none of them are in this package. • No multi-timeframe compression ranking. This evaluates one timeframe. • No tuned period, width multiplier, or squeeze threshold. • No default thresholds in code. scripts/squeeze_breakout.py raises PARAM_INCOMPLETE rather than falling back to a number. A silent default would make you believe you are running a calibrated system when you are running someone else's parameters. Every decision boundary is an input. That is the whole contract. DECISION CONTRACT • action: Condition • long: Previous close at or below the upper band and current close above it • exit: Previous close at or above the lower band and current close below it • flat: Inside the bands, or insufficient history Response carries bandwidth and squeezed, so the caller can log whether the breakout came out of compression even when the action is flat. OUTPUT SCHEMA { "action": "long", "price": 63390.0, "mid": 62900.0, "upper": 63350.0, "lower": 62450.0, "bandwidth": 0.0143, "squeezed": true, "reason": "squeeze breakout above the upper band (width 1.43%)" } action is the only field you must branch on. reason is meant for logs and for an agent to quote back to a human — do not parse it. RUN IT python3 scripts/squeeze_breakout.py \ --params references/params-example.json \ --symbol BTC/USDT \ --interval 1h references/params-example.json holds round, obviously-illustrative numbers. They exist so the command runs on the first try, not because they are good. Feeding position state in: python3 scripts/squeeze_breakout.py --params my.json --state '{"avg_entry": 61250.5, "layers": 2}' CALIBRATING THE THRESHOLDS 1. period - the window that defines "normal" for this instrument. Shorter reacts faster and produces more false compressions. 2. std_dev - how wide the envelope is. This is the parameter that most changes signal frequency; treat it as a sensitivity dial, not a quality dial. 3. squeeze_threshold - the width below which you call it compression. Measure the empirical distribution of bandwidth on your symbol first, then set the threshold at a low percentile of that distribution. Do not pick a round number. Because width is dimensionless, calibrate on one liquid symbol and sanity-check on another before trusting the transfer. Hold out the most recent ~30% of the sample. KNOWN LIMITS • The band is a simple moving average plus a population standard deviation; it is not the sample-standard-deviation variant some charting packages use. Numbers will differ slightly from a chart at the same settings. • squeezed describes the band after the current close, so on the breakout bar the band has already begun to widen. Use it as context, not as a pre-condition. • No volume confirmation. A band cross on no volume is treated identically to one on heavy volume. • The forming bar is excluded, so decisions do not repaint but also arrive one bar late by construction. DISCLAIMER This is a decision framework for research and education. It is not investment advice, not a profit claim, and not a backtest result. Crypto derivatives can lose more than the deposit. You are responsible for the parameters you choose and for every order your executor places.

What you get

• Width is measured as (upper - lower) / mid, so the same threshold is meaningful on a five-figure asset and a sub-dollar one
• The trigger is a band cross rather than the state of being outside the band, so each event fires once instead of every bar
• bandwidth and squeezed are returned even on non-signals, so a strategy that never fires can be diagnosed
• Population standard deviation is used consistently and documented, so numbers reconcile with your own tooling
• Framework release: period, width multiplier and squeeze threshold are all inputs

Onchain Identity

Public Metadata

Files

The primary-document hash is the SHA-256 of the plaintext primary Markdown file. The content-commitment hash covers the verified SkillRoot structure, or plaintext ZIP for older Skills; it is not the hash of the downloaded file.