RSI Zone Reversal

Description

The most common RSI bug is treating an extreme as an event. RSI below 30 can persist for dozens of bars in a downtrend, and a strategy that buys on the state will add into a falling market for as long as the state lasts. This package requires a transition: the previous RSI value must be inside the extreme zone and the current value outside it. That single condition removes the repeated-entry failure mode entirely and makes each signal a genuine change of state. The RSI itself is Wilder-smoothed, which is the original definition - different from the simple-average variant some libraries ship, so expect small numeric differences from a chart at identical settings. WHEN TO USE THIS • An agent has to decide whether an oversold reading is actionable yet. • You need a reversal entry that cannot fire twice on the same extreme. • You are diagnosing a mean-reversion strategy that keeps adding into a trend. Poor fit for strongly trending instruments: on a slow timeframe a trend can keep RSI above the overbought line for a very long time, so the exit never triggers. WHAT THIS PACKAGE DELIBERATELY DOES NOT CONTAIN This is a framework release, not the tuned production build. Specifically: • No position sizing or stop. Reversal entries need a hard invalidation level and that is yours to define. • No true divergence detection. Despite the family name, this implements the zone-transition rule, not a price/RSI swing comparison. Divergence detection needs swing identification, which is a separate and much more fragile problem. • No tuned period or zone levels. • No default thresholds in code. scripts/rsi_zone_reversal.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 RSI below the oversold line and current RSI at or above it • exit: Previous RSI above the overbought line and current RSI at or below it • flat: No zone transition Response carries rsi_now and rsi_prev so the transition - not just the level - is visible in your logs. OUTPUT SCHEMA { "action": "long", "price": 61840.0, "rsi_now": 29.4, "rsi_prev": 27.1, "oversold": 28.0, "overbought": 72.0, "reason": "RSI recovered out of oversold (27.1 -> 29.4)" } 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/rsi_zone_reversal.py \ --params references/params-example.json \ --symbol BTC/USDT \ --interval 4h 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/rsi_zone_reversal.py --params my.json --state '{"avg_entry": 61250.5, "layers": 2}' CALIBRATING THE THRESHOLDS 1. rsi_period - the lookback. Wilder smoothing makes the value respond slowly; a short period makes the zones meaningless because RSI oscillates through them constantly. 2. oversold / overbought - measure, do not guess. Compute the empirical distribution of RSI on your symbol and timeframe, then place the zone edges at the percentiles that produce the signal frequency you can actually act on. Symmetric 30/70 is a convention, not an optimum. 3. Keep the zones away from 0 and 100. Wide zones produce almost no transitions; very narrow zones produce transitions on noise. Hold out the most recent ~30% of bars. Count how many signals occur in each block - a rule that fires twice in a year is not calibratable, it is a coincidence. KNOWN LIMITS • Requires at least rsi_period + 2 closed bars before it can produce any transition; with less history it returns flat with a diagnostic. • Wilder smoothing means the first period values carry a fixed-seed bias. On short fetches this shows up as a shifted RSI level. • No trend filter. In a persistent downtrend the oversold transitions keep firing and each one loses; pairing this with a regime filter is strongly recommended and is left to the caller. • The forming bar is excluded, so decisions do not repaint. 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

• A transition is required, so a pinned RSI cannot re-trigger the same entry dozens of times
• Wilder smoothing is implemented explicitly, so the value matches the original definition rather than a simple-average approximation
• rsi_now and rsi_prev are both returned, so the transition - not just the level - is visible in your logs
• Zone validation rejects non-monotonic or absurdly wide zones instead of silently producing zero signals
• Framework release: the period and both zone edges are inputs, and the docs recommend empirical percentiles over the 30/70 convention

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.