/crypto-regime-analyzer

Crypto Regime Methodology

Scoring rationale, thresholds, and data schemas for crypto-regime-analyzer.

Design Principles

1. BTC-anchored. Bitcoin trend structure carries the largest weight (25%) because alt regimes rarely stay risk-on while BTC's primary trend is broken. Alt breadth and dominance are interpreted conditionally on BTC trend.
2. Contrarian at extremes, trend-following in the middle. Funding, drawdown, and momentum components give small contrarian bumps at washout extremes (near-total negative momentum, >65% drawdown with vol expansion, negative funding) because those readings historically coincide with improving forward returns — while remaining trend-respecting in normal ranges.
3. Degrade, never fail. Every component reports data_available; missing components have weight proportionally redistributed, mirroring market-breadth-analyzer.
4. Free and keyless. All live data comes from CoinGecko public + Binance public futures endpoints. Thresholds are heuristics chosen for interpretability, not backtest-optimized parameters — treat them as documented defaults to be revisited, not edge claims.

Component Details

1. BTC Trend Structure (25%)

Inputs: >= 220 daily BTC closes (200-day average plus a 20-day slope lookback).

Modifier: 200DMA slope over a 20-day lookback, +10 rising / 0 flat / -10 falling. Signal notes when the 50/200DMA gap is within 1.5% (imminent cross watch). Score clamped to [0, 100].

2. Alt Breadth Participation (20%)

Inputs: daily closes for the top-N universe excluding BTC; coins with < 200 observations are skipped and listed. Requires >= 5 usable alts.

Base from % above 200DMA: >=80% → 95, >=65% → 80, >=50% → 65, >=35% → 45, >=20% → 25, else 10. Modifier: 50DMA breadth leading 200DMA breadth by >= 15pts → +5 (fresh thrust); lagging by >= 15pts → -5 (rolling over).

3. BTC Dominance Regime (15%)

Inputs: >= 31 daily dominance observations + BTC-trend-constructive flag (Component 1 score >= 60). Direction = 30d change, ±0.5pt flat band.

Extremes: dominance >= 62% in a BTC downtrend → +5 (washout watch); <= 40% in an uptrend → -5 (froth caution).

4. Perpetual Funding Regime (15%)

Inputs: latest 8h funding rate per tracked USDT perp (>= 2 symbols). Average across symbols, banded:

5. Drawdown & Volatility Position (15%)

Inputs: >= 365 daily BTC closes. Base from drawdown vs trailing 1y high: <=10% → 90, <=20% → 75, <=35% → 55, <=50% → 35, <=65% → 20, else 10. Modifier: 30d realized vol (annualized, log returns) vs its trailing-1y distribution sampled at weekly stride — bottom third → +10, top third → -10. Contrarian floor: drawdown > 65% AND vol in top third → score floors at 15 (capitulation zone).

6. Momentum Thrust / Washout (10%)

Inputs: 31+ daily closes per coin, >= 5 usable coins, BTC included. % of universe with positive 30d return: >=85% → 90, >=65% → 75, >=45% → 55, >=25% → 35, >=10% → 20, <10% → 35 (washout: contrarian bump over the plain mapping).

Composite & Zones

Weighted average over available components with proportional weight redistribution only when at least four components representing at least 65% of original model weight remain. Sparser inputs return UNKNOWN. Zones are heuristic descriptive bands: 80-100 RISK_ON, 40-79 NEUTRAL, and 0-39 RISK_OFF. They are not validated allocation rules; see VALIDATION.md for the evidence boundary and reproduction requirements.

Offline Snapshot Schema (--input-json)

{
  "as_of": "2026-07-01T00:00:00Z",
  "series": {
    "BTC": [45000.0, 45210.5, "... daily closes oldest -> newest ..."],
    "ETH": [2400.0, 2415.2],
    "SOL": [140.0, 141.8]
  },
  "dominance_series": [56.1, 56.0, 55.8],
  "funding": {
    "BTCUSDT": 0.0001,
    "ETHUSDT": 0.00008
  }
}

Rules:

• series must include a "BTC" key; all other keys are treated as alts.
• Closes are finite positive numbers, oldest -> newest, ideally 400+ observations (220 minimum for BTC trend, 365 for drawdown/vol, 200 for alt breadth membership).
• dominance_series is daily BTC dominance percentages oldest -> newest; empty list is allowed (component degrades).
• dominance_series values must be finite percentages greater than 0 and at most 100.
• funding values are finite decimal 8h rates (0.0001 = +0.010%) in the inclusive range [-1, 1]; empty object is allowed (component degrades). The deliberately wide range is a numerical-safety guard, not a claim that such extreme rates are economically plausible.

Data Sources (live mode)

Fetches are throttled at ~6.5s between history calls to respect CoinGecko's free-tier limits and cached per UTC day under --cache-dir.