crypto-regime-analyzer

Crypto Regime Analyzer Skill

Purpose

Quantify the crypto market regime using a data-driven 6-component scoring system (0-100). This is the crypto analog of market-breadth-analyzer + exposure-coach: it answers "what posture does the crypto market currently support?" before any coin-level analysis happens.

Score direction: 100 = Maximum risk-on health (broad participation, healthy trend, sane leverage), 0 = Critical risk-off.

No API key required — uses CoinGecko's free public API and Binance's public futures endpoint.

When to Use This Skill

• User asks "Is crypto risk-on or risk-off right now?" or "How healthy is the crypto market?"
• User asks "Is it alt season?" or about BTC dominance direction
• User asks whether funding rates are overheated
• User wants an exposure posture for a crypto sleeve before screening individual coins
• User wants a daily crypto regime check alongside the equity market-regime-daily workflow

What This Skill Does NOT Do

• No coin picks, no buy/sell signals, no price targets
• No execution or portfolio changes — regime description only
• Human decision gates remain central, consistent with the project vision

Prerequisites

• Python 3.9+ with requests (live mode only; offline mode is stdlib-only)
• Internet access to api.coingecko.com and fapi.binance.com (live mode)
• No API keys required

Component Model

Missing components have their weight proportionally redistributed (same convention as market-breadth-analyzer). Full scoring logic: references/crypto_regime_methodology.md.

Regime Zones

These are heuristic descriptive bands, not validated allocation rules. See references/VALIDATION.md for the current evidence boundary and the artifacts required before making quantitative performance claims.

Execution Workflow

Phase 1: Run the Analysis Script

Live mode (fetches CoinGecko + Binance; first run of the day takes ~2-4 minutes at the default --top-n 20 due to free-tier rate-limit throttling; same-day re-runs hit the cache and are instant):

mkdir -p reports/<routine-or-date>
python3 skills/crypto-regime-analyzer/scripts/crypto_regime_analyzer.py \
  --output-dir reports/<routine-or-date>

Offline mode (no network; snapshot schema in the methodology reference):

python3 skills/crypto-regime-analyzer/scripts/crypto_regime_analyzer.py \
  --input-json snapshot.json \
  --output-dir reports/<routine-or-date>

Options: --top-n <int> universe size (default 20), --cache-dir <path> fetch cache location (default .crypto_regime_cache), --quiet.

Phase 2: Interpret the Output

The script writes crypto_regime.json (machine-readable, for chaining into other skills) and crypto_regime.md (one-page report), and prints a one-line summary:

CRYPTO REGIME: NEUTRAL (score 68.4/100) — Mixed conditions observed; no strong regime conclusion

When presenting results, lead with the zone and posture, then explain the 1-2 components most responsible for the score using their signal strings. Flag any components reporting data_available: false and what that means for confidence.

Phase 3 (optional): Feed Downstream

The JSON composite can slot into an exposure-coach-style posture summary as one descriptive crypto-market input. It must not independently authorize, block, size, or execute a trade.

Output

The script writes two artifacts to --output-dir and prints a one-line summary for workflow chaining:

• crypto_regime.json — full machine-readable analysis: metadata, per-component results (score, signal, data_available, component-specific fields), and the composite block (score, zone, guidance, effective_weights).
• crypto_regime.md — one-page report: composite score with zone bar, posture line, per-component table (weight / score / signal), and confidence notes.
• Console: CRYPTO REGIME: <ZONE> (score <N>/100) — <posture> plus warnings for any skipped components.

Resources

• references/VALIDATION.md — validation status, evidence boundary, and reproduction requirements.
• references/crypto_regime_methodology.md — full scoring rationale, every threshold table, the offline snapshot JSON schema, and the live data-source endpoint list.
• scripts/crypto_regime_analyzer.py — CLI orchestrator (entry point).
• scripts/data_client.py — CoinGecko/Binance fetchers, per-day cache, dominance history accumulator, offline loader.
• scripts/calculators/ — one module per component; pure functions, fully unit-tested.
• scripts/scorer.py — weighted composite with proportional weight redistribution.
• scripts/tests/ — tests covering every component, the scorer, sparse-data fail-closed behavior, and end-to-end bull/bear/degraded snapshots.

Known Limitations

• Dominance history accumulates locally. CoinGecko's free tier only exposes current dominance, so the client stores one observation per run-day in the cache dir. The dominance component reports data_available: false until 31 daily observations exist (weight is redistributed until then). Seed it faster via --input-json.
• Funding is best-effort. If Binance's endpoint is unreachable (geo-restrictions, outage), the component is skipped gracefully.
• Universe is top-N by market cap with stablecoins and wrapped/staked assets excluded; it is not a fixed index, so composition drifts with the market.
• Thresholds are heuristic and documented in the methodology reference; they are conservative defaults, not backtested optima.

Disclaimer

Educational and process-improvement use only. This skill describes market conditions; it does not provide financial advice, signals, or buy/sell instructions. All decisions remain the user's responsibility.