Session Range Breakout

Description

Session breakouts work because a fixed slice of the clock concentrates liquidity into a defined range. They fail for a boring reason: implementations include the current bar in the range, which makes range_high >= last_price true by construction, so the upside break can never fire. The strategy silently only ever sells. This package excludes the forming bar from the range by design and computes the window on UTC hour-of-day, including wrap-around windows such as 22:00 to 02:00. The breakout tolerance is a separate input so you can require a decisive close rather than a touch. WHEN TO USE THIS • An agent needs a breakout rule that is conditioned on when the range formed. • You are comparing session-conditioned behaviour across symbols or venues. • You want a worked example of the "current bar contaminates the range" bug and the fix, because it is one of the most common silent failures in this family. Not suitable for 24-hour markets with no meaningful session structure - the range will simply mirror recent volatility. WHAT THIS PACKAGE DELIBERATELY DOES NOT CONTAIN This is a framework release, not the tuned production build. Specifically: • No position sizing. The clip size is yours. • No stop placement. A failed breakout needs a stop; that rule is not here. • No timezone conversion. The window is interpreted in UTC, full stop. If you trade a local session you must convert before calling. • No tuned window or tolerance values. • No default thresholds in code. scripts/session_range_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: Last close is at or above the session high times (1 + tolerance) • exit: Last close is at or below the session low times (1 - tolerance) • flat: Inside the range, or fewer than two in-session bars Response carries session_high, session_low and in_session_bars so the caller can verify the range was built from the hours it intended. That check matters more than the signal itself. OUTPUT SCHEMA { "action": "long", "price": 63240.0, "session_high": 62970.5, "session_low": 62210.0, "in_session_bars": 13, "reason": "closed 0.43% above the session high 62970.50" } 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/session_range_breakout.py \ --params references/params-example.json \ --symbol BTC/USDT \ --interval 30m 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/session_range_breakout.py --params my.json --state '{"avg_entry": 61250.5, "layers": 2}' CALIBRATING THE THRESHOLDS 1. session_start / session_end - HH:MM in UTC. The window must contain enough bars at your chosen interval to form a meaningful range; at a 30m interval a two-hour window gives you four bars, which is thin. Count the bars first, then choose the window. 2. breakout_threshold - the decisiveness requirement. At zero you trade every touch of the edge and get chopped; too large and the move is already spent. Anchor it to typical bar range rather than to a round percentage. Calibrate the window and the tolerance jointly - the optimal tolerance depends on how tight the window's range is. Hold out the most recent ~30% of the sample in time and confirm the pair still holds before trusting it. KNOWN LIMITS • The range is rebuilt on every call from the bars you pass in, and uses only the most recent contiguous in-session run. If your --limit does not span back past the start of that session, the range is partial and the levels are wrong. Fetch comfortably more than one session worth of bars. • Wrap-around windows (start later than end) are supported, but a window that spans the fetch boundary will still be partial. • No volatility or volume condition: a low-liquidity session produces a narrow range and near-continuous breakouts. • The forming bar is excluded from the range but is used as the trigger price, so intra-session signals can appear before the bar closes. 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

• The current bar cannot leak into its own range, which fixes the most common silent failure in this strategy family
• Only the most recent contiguous session is used, so the range reflects hours price actually traded rather than a multi-day composite
• Wrap-around windows (start later than end) are handled explicitly, so a 22:00-02:00 session works
• in_session_bars is reported on every call, so you can verify the range was built from the hours you intended
• Framework release: the window and the tolerance are inputs, not shipped values

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.