# 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`](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/`](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

```bash
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

```bash
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`](packaging/cmc-skill/skill.md)
  and [`skill.json`](packaging/cmc-skill/skill.json)
- MCP client config: [`packaging/cmc-skill/mcp_config.json`](packaging/cmc-skill/mcp_config.json)
- Server: [`src/market_regime_oracle/mcp_server.py`](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.