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:

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.

Related MCP server: riskstate-mcp

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.

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

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.