Skip to main content
Glama
Market Regime Oracle

Market Regime Oracle

by aggreyeric

πŸ“Š Market Regime Oracle

A 5-signal β†’ 5-state BTC market-regime classifier with posture mapping, backtested vs buy-and-hold.

Fuses momentum, sentiment, volatility, funding & flow into one explainable regime β€” and a documented risk posture per regime.

Python License: MIT Tests Track MCP


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

🟒 RISK_ON

100%

Uptrend β€” full exposure

🟑 RANGE_BOUND

40%

Sideways β€” light exposure

πŸ”΅ RISK_OFF

20%

Downtrend β€” defensive

πŸ”΄ CAPITULATION

10%

Panic β€” max defensive

🟣 EUPHORIA

30%

Blow-off β€” take profit

Built as an MCP Strategy Skill for the CoinMarketCap Agent Hub (BNB AI Trading β€” Track 2). Any MCP-compatible client (Claude Desktop, Cursor, CMC Agent Hub) calls get_market_regime to get a deterministic, no-look-ahead risk posture.


Related MCP server: PreReason-mcp

πŸ“ˆ Headline Result

In a down year for BTC (βˆ’37%), the regime strategy did βˆ’12.7% β€” halving drawdown (βˆ’24% vs βˆ’51%) and halving volatility (19% vs 43%), outperforming buy-and-hold by ~25 points while still going long in uptrends.

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

Data: CoinGecko BTC daily (2025-06-19 β†’ 2026-06-17, 364 days). Start $10,000. 10 bps/turnover cost.


πŸ–ΌοΈ Visual Results

Equity Curve β€” Regime Strategy vs Buy & Hold

Drawdown β€” Strategy Stays Shallower

BTC Price with Regime Overlay

Regime Distribution & Target Exposure


πŸ—οΈ Architecture

  CoinGecko (BTC OHLCV)         alternative.me (Fear & Greed)
         β”‚                              β”‚
         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                        β–Ό
             β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
             β”‚   data/loader.py    β”‚  aligned daily features
             β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                       β–Ό
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚     5 independent signal modules         β”‚  each β†’ score in [-1, +1]
  β”‚  momentum(0.30)  fear_greed(0.25)        β”‚
  β”‚  funding(0.15)   flows(0.15)   vol(0.15) β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                         β–Ό weighted fusion
                  composite score
                         β–Ό priority rules
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚   5-state regime classifier              β”‚  CAPITULATION > EUPHORIA >
  β”‚   (deterministic, no look-ahead)         β”‚  RISK_OFF   > RISK_ON >
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                          > RANGE_BOUND
                         β–Ό
                target exposure + action
           β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
           β–Ό                               β–Ό
    vectorized backtest                MCP tool: get_market_regime
    (no look-ahead, w/ costs)          (stdio, Agent Hub skill)

🧩 The 5 Signals

Signal

Source

Weight

RSI / MACD momentum

CoinGecko price

0.30

Fear & Greed Index

alternative.me

0.25

Volatility regime

CoinGecko price

0.15

Funding rate proxy

derived from price

0.15

Exchange flow proxy

derived from volume

0.15

Each signal outputs a normalized bullishness score in [-1, +1]. All 5 are independently unit-tested.

Transparency: Funding rate and exchange flows have no free public feed. We reconstruct them from price/volume data as clearly-labeled proxies. Drop in real feeds anytime β€” the fusion layer is signal-agnostic.


πŸš€ Quick Start

git clone https://github.com/aggreyeric/bnb-market-regime-oracle.git
cd bnb-market-regime-oracle
pip install -r requirements.txt

# Run full pipeline: fetch β†’ classify β†’ backtest β†’ charts
python main.py

# Run tests (offline, no network needed)
PYTHONPATH=src python -m pytest tests/

# Run as MCP server
PYTHONPATH=src python -m market_regime_oracle.mcp_server

# Live MCP demo (30 seconds)
./scripts/demo.sh

Docker

docker compose up --build run    # full pipeline
docker compose up --build server # MCP server

πŸ“ Project Layout

market_regime_oracle/
β”œβ”€β”€ src/market_regime_oracle/
β”‚   β”œβ”€β”€ data/          # CoinGecko + alternative.me loaders
β”‚   β”œβ”€β”€ signals/       # 5 signal modules (unit-tested)
β”‚   β”œβ”€β”€ classifier/    # fusion β†’ regime mapping
β”‚   β”œβ”€β”€ backtest/      # vectorized engine, no look-ahead
β”‚   β”œβ”€β”€ viz/           # equity/drawdown/regime charts
β”‚   └── mcp_server.py  # MCP stdio server
β”œβ”€β”€ tests/             # 24/24 passing
β”œβ”€β”€ results/           # CSVs, metrics.json, PNG charts
β”œβ”€β”€ scripts/demo.sh    # live MCP round-trip
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ docker-compose.yml
└── README.md

πŸ“š Data Sources

  • CoinGecko v3 free API β€” BTC daily close + volume

  • alternative.me β€” Fear & Greed Index

Both public, both free. No API keys required.


πŸ“œ License

MIT Β© 2026

πŸ€– AI Assistants

β†’ See CLAUDE.md for AI coding assistant context.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      AI-powered crypto signal intelligence for 20 assets (BTC, ETH, SOL, etc). 6 scoring dimensions: whale activity, technical analysis, derivatives flow, narrative strength, sentiment, market structure. Market regime detection (TRENDING/RANGING), portfolio optimization, and accuracy tracking. 9 read-only MCP tools. Free via MCP, $0.001 USDC via x402 on Base for REST API.
      3
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      PreReason is a financial data MCP server and REST API for AI agents. Ask what a listed company reported, where Treasury yields stand or what the Federal Reserve decided, and one call returns a briefing reasoned in advance, across asset classes and regions, with every figure dated and every source named. Agents start at https://www.prereason.com/agents.md
      8
      220 npm
      8
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Deterministic risk governance for crypto trading agents. 5-level policy engine with position sizing, leverage limits, and trade blocking. One tool: get_risk_policy. Supports BTC and ETH.
      4
      72 npm
      1
      MIT