Market Regime Oracle — CMC Strategy Skill

A CoinMarketCap Agent Hub Strategy Skill (BNB Chain AI Trading Agent — Track 2) that fuses 5 market signals into a 5-state regime classifier, maps each regime to an explicit trading posture, and backtests the result against buy-and-hold with demo-ready equity-curve charts.

⚠️ Research / backtest artifact — Track 2 only. No live trading, no wallet connection, no token launch. Not submitted to any contest portal; only the admin approves submissions. Nothing here is financial advice.

---

TL;DR — what it does

Ask: "What kind of BTC market is this, and how much risk should I take?"

The oracle answers with one of 5 regimes + a documented posture:

Regime	Target exposure	Posture / action
RISK_ON	100%	Uptrend — accumulate, full exposure
RANGE_BOUND	40%	Sideways — light exposure, hold core
RISK_OFF	20%	Downtrend — defensive, raise cash to ~80%
CAPITULATION	10%	Panic sell-off — max defensive, near-full cash
EUPHORIA	30%	Blow-off top — take profit, fade strength

The classifier is a priority-ordered, deterministic rule hierarchy over a fused composite score (extreme regimes CAPITULATION / EUPHORIA override the trend regimes). See src/market_regime_oracle/classifier/fusion.py.

---

Backtest result (real BTC data, ~1y)

Data: CoinGecko BTC daily (2025-06-19 → 2026-06-17, 364 days). Start capital $10,000. Transaction cost 10 bps per unit of turnover. Strategy = regime posture; benchmark = 100% BTC buy-and-hold.

Metric	Regime Strategy	Buy & Hold
Total return	−12.7%	−37.4%
Max drawdown	−24.2%	−51.2%
Annualized volatility	19.3%	43.1%
Sharpe (rf 4%)	−0.82	−0.97
Sortino	−1.01	−1.32
Final equity	$8,733	$6,264

Reading: over a down-trending year (BTC −37%), staying defensive in RISK_OFF / CAPITULATION cut the drawdown roughly in half and more than halved volatility, outperforming buy-and-hold by ~25 points while still being long BTC in RISK_ON. Regime mix observed: RISK_OFF 38%, RISK_ON 27%, RANGE_BOUND 25%, CAPITULATION 8% (acute panics), EUPHORIA 1.6% (blow-off).

Charts (regenerated in results/): equity_curve.png, regime_overlay.png, drawdown.png, regime_summary.png.

---

The 5 signals

#	Signal	Source	Real?
1	Funding rate sentiment	— (proxy from price)	⚠️ proxy
2	Fear & Greed Index	alternative.me	✅ real
3	Exchange flow pressure	— (proxy from volume)	⚠️ proxy
4	RSI / MACD momentum	CoinGecko price	✅ real
5	Volatility regime	CoinGecko price	✅ real

Each signal outputs a normalized bullishness score in [-1, +1] and is an independently runnable, unit-tested module under src/market_regime_oracle/signals/.

Assumptions & proxies (transparency)

The hard rules allow only CoinGecko + alternative.me (public, free). Two signals have no free public feed, so they are clearly-labeled proxies reconstructed from authorized price/volume data — not fabricated "real" data:

• Funding rate (proxy). Funding reflects crowded directional bets: strongly positive when the market overheats (longs pay shorts), negative during flushes. We approximate it with a risk-adjusted momentum term (recent return ÷ its vol). Columns prefixed funding_proxy_*.
• Exchange flows (proxy). True on-chain flows need paid data. We reconstruct flow pressure from signed volume (volume × sign of return): high-volume up days ≈ accumulation/outflows (risk-on), high-volume down days ≈ distribution/ inflows (risk-off). Columns prefixed flow_proxy_*.

If you later connect a real funding/on-chain feed, drop in a new Signal subclass — the fusion layer is feed-agnostic.

---

Quick start

pip install -r requirements.txt

# run the full pipeline: fetch -> classify -> backtest -> charts -> save results
PYTHONPATH=src python -m market_regime_oracle.run          # or: python main.py

# run the test suite (offline, synthetic data — no network)
PYTHONPATH=src:tests python -m pytest tests/

# run as a CMC Agent Hub skill (MCP server over stdio)
PYTHONPATH=src python -m market_regime_oracle.mcp_server

Outputs land in results/ (CSVs, metrics.json, PNG charts) and raw JSON is cached under data_cache/ to stay gentle on free rate limits.

From a clean clone

git clone <repo> && cd market_regime_oracle
pip install -r requirements.txt
python main.py          # reproduces all results/ artifacts

---

CMC Agent Hub skill packaging

Packaged as an MCP server — the same model the CMC Agent Hub uses to route prompts to cloud Skills. Any MCP-compatible client (Claude Desktop, Cursor, OpenClaw, VS Code, the CMC Agent Hub) can call the get_market_regime tool.

• Manifest (marketplace format): packaging/cmc-skill/skill.md and skill.json
• MCP client config: packaging/cmc-skill/mcp_config.json
• Server: src/market_regime_oracle/mcp_server.py
• Verify the skill runs end-to-end: PYTHONPATH=src MRO_HOME=. python tests/_mcp_smoke.py (performs a real initialize → tools/list → tools/call round-trip)

The CMC MCP already exposes the raw primitives this skill fuses (get_crypto_technical_analysis, get_global_metrics_latest, get_global_crypto_derivatives_metrics, on-chain metrics); this skill is the fusion + posture layer on top.

---

Architecture

data/        CoinGecko (BTC price+vol) + alternative.me (Fear & Greed), cached
  └─ loader  builds the aligned daily feature frame
signals/     5 independent, unit-tested signal modules -> score in [-1,1]
classifier/  weighted fusion -> composite -> priority rule hierarchy -> regime
  └─ posture regime -> target exposure + documented action
backtest/    vector engine, no look-ahead, with costs; metrics + trade log
viz/         matplotlib equity / drawdown / regime-overlay / summary charts
mcp_server   exposes get_market_regime + list_regimes over MCP stdio
run.py       end-to-end pipeline + CLI

Decision model (no look-ahead): the regime and target exposure are decided at day t's close from information up to and including t; the position earns the t → t+1 BTC return. Rebalancing incurs a linear transaction cost.

---

Project layout

market_regime_oracle/
├── README.md                 # this file
├── requirements.txt          # pinned deps
├── pyproject.toml            # installable package + console script
├── main.py                   # convenience entry point
├── src/market_regime_oracle/ # core package (data, signals, classifier, backtest, viz, mcp_server, run)
├── tests/                    # pytest: signals, classifier, backtest, mcp smoke
├── packaging/cmc-skill/      # CMC Agent Hub skill manifest + mcp_config
├── results/                  # generated CSV/JSON + PNG charts (demo artifacts)
└── data_cache/               # cached raw API responses (gitignored)

---

Data sources

• CoinGecko v3 public free API — BTC daily close + volume.
• alternative.me — Fear & Greed Index history.

Both are public and free. No API keys are required or stored.

Hard rules enforced

• ✅ Track 2 only — research / backtest.
• ✅ No live trading, no wallet connection, no token launch.
• ✅ Not submitted to DoraHacks or any portal — admin approval only.
• ✅ Only authorized public/free sources; proxies are clearly labeled.