Momentum Candle Backtester
Internals & Decision Record

A three-gate validation pipeline for altcoin breakout candles

The scanner finds momentum breakout candles across 300+ Binance USDT pairs. Each candidate signal is pushed through three sequential gates before any execution decision is made:

Three files. One brain.

Dependencies

# requirements.txt
streamlit>=1.32.0
plotly>=5.19.0
pandas>=2.0.0
numpy>=1.26.0
scipy>=1.12.0
scikit-learn>=1.4.0
requests>=2.31.0

Three tabs, three concerns

One signal, three steps, one verdict

Binance klines, 1000 bars deep

All backtest/WFO/ML training pulls from _scanner_fetch_candles(symbol, interval, limit). Binance's /api/v3/klines hard-caps at 1000 bars — we always fetch the max.

_BINANCE_INTERVAL = {"1D":"1d", "4H":"4h", "1H":"1h", "1W":"1w"}
_DEEP_FETCH_LIMITS = {"1h":1000, "2h":1000, "4h":1000,
                      "6h":1000, "12h":1000, "1d":1000}

What 1000 bars means per timeframe

Every feature is strictly past-looking

Built by _clean_df(df). Audited by lookahead_audit.py — 20/20 CLEAN (synthetic test, 25 random bars, all features match causal recomputation). A deliberately-leaking test feature was correctly flagged — the audit works.

The 11 ML features (subset of 22)

A 0–100 score blending trend, sentiment, funding, OI

calculate_regime_score(df, bar_index, direction, adx_df, timeframe, ticker) composites four inputs into a single bar-level score. The score is cached per bar in _bar_regime_cache so the 72-method backtest doesn't recompute it 72× per candle.

Soft regime similarity

def _regime_similarity_weight(current, historical):
    return max(0.15, 1 - abs(current - historical) / 100)

Applied to:

• Backtest EVw / WRw — analogs from similar regimes pull harder
• ML sample_weight — same logic, at the classifier level

NOT applied to WFO — WFO tests generalization across regimes on purpose. Regime-filtering the WFO would defeat the point.

Finds breakout candidates across 300+ USDT pairs

Universe built by _scanner_get_universe(min_volume_usdt) — Binance spot USDT pairs with min 24h volume. Each coin scans its last 3 closed candles (not current bar — that's still forming) via _scan_one_symbol → _scanner_score_signal.

Scoring a candidate

_scanner_score_signal(df, adx_df, bar_idx, direction,
                       timeframe, symbol, min_body_pct, min_vol_mult)
#  → returns sig dict  OR  None if below threshold

Returns a sig dict containing: direction, entry/SL/TP prices, body_pct, vol_mult, ADX, DI gap, ATR ratio, EMA alignment score, regime score, bar_index, timeframe, symbol, 11-feature vector extracted for current bar.

72 method combos against historical analogs

When the user clicks "Run Step 1": _scanner_quick_backtest(sig) scans historical bars looking for analogs to the current signal, then simulates all 72 method combinations on those analogs. _scanner_mini_wfo(sig, bt) then runs a rolling purged walk-forward on the full df to test generalization.

Key constants

NEUTRAL_R_THRESHOLD = 0.30        # ±0.30R = NEUTRAL, excluded from ML
MAX_HOLD            = 20          # max bars per trade
FIXED_SL            = 1.5%        # fixed stop width (alt: ATR SL)

Progressive relaxation when analogs are scarce

Problem: a strong 85%-body, 5× volume signal has very few exact historical analogs. Requiring 70% of its own body/vol would find 4 samples on ETH 4H. Too few to backtest, way too few to train ML on.

Solution: a ratchet that relaxes the threshold until enough samples are found, with hard floors to prevent pure-noise analogs.

# Backtest ratchet (target: 50 bars)
_BT_RATCHET_RATIOS = [0.70, 0.55, 0.45, 0.35, 0.25, 0.20]
_BT_MIN_BODY_FLOOR = 0.20
_BT_MIN_VOL_FLOOR  = 1.10

# ML ratchet (target: 80 samples)
_RATCHET_RATIOS = [0.70, 0.55, 0.45, 0.35, 0.25, 0.20]

UI badge

The result flows through to a user-facing badge:

STRICT 70% — analogs tightly matched, trust ML probability numerically. RELAXED 45% — broad analog set. LOOSE 20% — very broad; treat ML probability as directional only.

Every signal tested against 72 trade strategies

The cartesian product of entry × SL × mgmt × TP:

ENTRY_ZONES  = ["Aggressive", "Standard", "Sniper"]              # 3
SL_METHODS   = ["Fixed SL", "ATR SL"]                           # 2
MGMT_MODES   = ["Simple", "Partial", "Partial-NoBE", "Trailing"]   # 4
TP_MULTS     = [2.0, 2.5, 3.0]                                  # 3
#            3 × 2 × 4 × 3 = 72 combinations

Entry zones

Management modes

All 72 methods (visual)

72 combinations · each with n, WR, EV, EVw, PF, fill_rate, 4-bucket decay breakdown

The dual-candidate decision system

Rather than picking a single "best" method from the 72, the system surfaces two:

bt["candidate_newest"]

bt["candidate_weighted"]

Time-decay bucket scheme (adaptive)

5 rolling windows with de Prado-style purge + embargo

A single in-sample/out-of-sample cut is one point estimate. Five rolling cuts give a distribution. "5/5 windows OOS PF ≥ 1.0" is real edge; "1 good cut" could be luck.

Rolling cuts at 50/60/70/80/90%

Purge + embargo (de Prado Ch.7)

Every trade stores bar_index (entry bar) and label_end_bar (= j, resolution bar). PurgedTimeSeriesSplit drops training samples whose label period overlaps the test fold. Embargo = ceil(0.01 × n_total) after each fold.

WFO verdict thresholds

{
  "ok": bool,
  "verdict": "PASS" | "BORDERLINE" | "FAIL" | "INSUFFICIENT",
  "is_pf", "oos_pf", "oos_wr",
  "is_pf_clean", "oos_pf_clean",      # honest PF excl. NEUTRAL
  "oos_n": int,
  "purge_diag": {n_purged, n_embargoed, embargo_bars},
  "label_diag": {n_neutral, raw_pf, honest_pf, pf_inflation_pct},
  "oos_pf_ci": {"lo": float, "hi": float},  # 1000-resample block bootstrap
  "rolling_wfo": {"edge_hit_rate", "windows": [...]},
  "regime_breakdown": {"STRONG": ..., "MID": ..., "WEAK": ...},
  "tier_label": "PURGED IS/OOS split (70%/30%, embargo 1%)",
}

Classifier picked by sample count

Different sample sizes need different models. Too few samples and a heavy model overfits; too many and a simple model underutilizes the data.

Calibration wrapper

if n_samples >= 60:
    model = CalibratedClassifierCV(model, method="isotonic", cv=3)

CV splitter

cv = PurgedTimeSeriesSplit(
    n_splits=min(5, n // 15),
    embargo_pct=0.01,
)
# Never sklearn's default TimeSeriesSplit — would leak labels at fold boundaries.

The |r_mult| ≤ 0.30R band excluded from ML

def _classify_outcome(r_mult):
    if r_mult >  NEUTRAL_R_THRESHOLD:  return "WIN"
    if r_mult < -NEUTRAL_R_THRESHOLD:  return "LOSS"
    return "NEUTRAL"

• NEUTRAL trades still counted in PF/WR accounting (the money is real).
• NEUTRAL trades excluded from ML labels (they'd cause single-class collapse on trending coins).
• WFO reports honest_pf (excluding NEUTRAL) alongside raw PF.

Every training sample gets a two-factor weight

sample_weight = time_decay_bucket_weight × regime_similarity_weight

Groq reasoning with canonical prices

_scanner_ai_verdict(sig, ml_a, ml_b, bt, wfo, cand_a, cand_b)
#  → {candidate_a, candidate_b, winner, winner_rationale}

Model selection

reasoning_effort="medium" only for gpt-oss/qwen. max_tokens=2500. Timeout 60s.

Price hallucination prevention

_compute_candidate_prices(cand, sig) is the single source of truth for entry/SL/TP1/TP2 prices. Both the UI cards and the AI prompt read from it. The AI prompt contains an explicit EXECUTION PRICES block with a "copy verbatim" instruction.

Dual verdict rules

• When A == B (unanimous): single analysis mirrored to both sides.
• Both TRADE → AI picks stronger as winner.
• Only one TRADE → that one wins.
• Neither → winner = NONE.

Dual-candidate-aware A+ / A / B / C

_scanner_setup_grade(sig, ml, bt) grades by best-of the two candidates. A previous bug read from legacy aggregate bt["win_2r"], which made Cand A excellent + aggregate bad return "C — Backtest negative" (false negative).

Rescue rules

• "B rescue" — if any candidate is tradeable AND ml_pct ≥ 60, grade won't drop below B.
• Grade color follows the badge palette: A+ A B C.

On-chain Nansen-lite, free tier

get_pulse_intel(symbol,
                etherscan_api_key, lunarcrush_api_key, solscan_api_key)
#  → composite_score (-15 to +15)
#  → composite_label: STRONGLY BULLISH / BULLISH / NEUTRAL / BEARISH / STRONGLY BEARISH

Composite weights

Per-token composite scaled ×1.2 → ±12. Macro modifier (±3) added on top → final ±15.

Things that must stay exactly as they are

1. Never use sklearn TimeSeriesSplit — always PurgedTimeSeriesSplit. Label-period overlap leaks.
2. best_key uses ev_weighted, not raw ev. Fixed bug.
3. Don't remove label_end_bar from trades_raw. Purge depends on it.
4. Don't remove the ratchet. High-vol signals get 0–6 training samples without it.
5. Don't remove NEUTRAL classification. Prevents single-class ML collapse on trending coins.
6. Zone validity is correct. Do NOT widen SL to "fix" it.
7. WFO is NOT regime-filtered by design. Keep it that way.
8. _compute_candidate_prices is the single source of truth for AI prompt + UI.
9. Dead code in render_auto_analyzer (manual_sig=None, _manual_render_signals block ~L4394-4430). Harmless. Do NOT activate without a dedicated session.
10. def main(): must exist. A prior str_replace edit accidentally removed it, causing NameError on deploy. Always verify before shipping.

Intentionally NOT built

Current state