# Bitcoin Accumulation Zone Monitor

> Bitcoin on-chain metrics dashboard with classic equal-weight scoring, ML-optimized scoring, historical backtesting, and click-to-select metric context for long-term BTC accumulation decisions.

![Dashboard](screenshots/dashboard-main.png)

## What It Does

Monitors Bitcoin accumulation conditions using 16 scored market/on-chain indicators plus optional informational cycle metrics. Each scored metric receives a 0-10 score and rolls into a 0-100 accumulation score.

The dashboard now supports two scoring modes:

- **Classic** — transparent equal-weight scoring across every active metric.
- **ML** — feature-importance weights trained against historical 365-day forward returns, with displayed per-metric weights and point contributions.

Historical backtests show score-vs-price behavior, score bracket performance, major signal events, and current-score context. Metric cards are clickable: selecting a metric overlays its historical series on the score chart and shows comparable historical periods with forward returns.

## Screenshots

### Main Dashboard — ML mode + metric context
![Main Dashboard](screenshots/dashboard-main.png)
*Live BTC price, Classic/ML scoring toggle, 16 active scored metrics, ML weights/contributions, metric sparklines, and click-to-select historical context.*

### Historical Backtest
![Backtest](screenshots/dashboard-backtest.png)
*Current signal percentile, comparable historical periods by cycle, score-vs-BTC chart, bracket performance, and major signal events.*

### Settings
![Settings](screenshots/dashboard-settings.png)
*LLM provider configuration for optional AI-powered signal commentary and local/cloud model selection.*

## Feature Highlights

- **16 scored metrics** from market sentiment, miner stress, valuation, holder behavior, network activity, and velocity signals.
- **Classic vs ML scoring toggle** on the dashboard and backtest API.
- **ML score explainability**: metric cards show learned weight and contribution in points.
- **Leakage-resistant ML validation**: training uses purged time-series splits so 365-day forward-return labels do not overlap validation windows.
- **Historical context panel**: compares the current composite score against historical periods and forward returns.
- **Clickable metric cards**: select any metric to see percentile, similar historical levels, forward returns, example dates by market cycle, and highlighted chart periods.
- **Score history chart** with BTC price overlay, range controls, and selected-metric overlay.
- **Backtest dashboard** with current signal context, score bracket performance, and signal-crossing events.
- **Quick vs full refresh**: quick refresh updates BTC price and Fear & Greed; full refresh re-scrapes on-chain sources.
- **LLM settings UI** for Ollama, LM Studio, OpenAI, Anthropic, and OpenRouter.

## Metrics

| # | Metric | Source | Accumulation Signal |
|---|--------|--------|-------------------|
| 1 | Fear & Greed Index | alternative.me API | Extreme fear / capitulation sentiment |
| 2 | Puell Multiple | LookIntoBitcoin | Miner revenue stress |
| 3 | MVRV Z-Score | LookIntoBitcoin | Market near/below realized value |
| 4 | Drawdown from ATH | Calculated from BTC price | Deep correction from cycle high |
| 5 | Price vs 200W SMA | LookIntoBitcoin + BTC price | Price near/below long-term trend |
| 6 | Reserve Risk | LookIntoBitcoin | High holder confidence relative to price |
| 7 | RHODL Ratio | LookIntoBitcoin | Long-term holder dominance |
| 8 | Net Unrealized Profit/Loss (NUPL) | LookIntoBitcoin | Capitulation / early recovery zones |
| 9 | LTH Realized Price | LookIntoBitcoin | Price near long-term holder cost basis |
| 10 | Hash Ribbons | LookIntoBitcoin | Miner capitulation/recovery signal |
| 11 | SOPR | CheckOnChain | Spent outputs near loss / reset territory |
| 12 | Sell-side Risk Ratio | CheckOnChain | Low realized profit/loss pressure |
| 13 | Active Address Momentum | CheckOnChain | Network activity momentum extremes |
| 14 | Transaction Count Momentum | CheckOnChain | Transaction activity momentum extremes |
| 15 | NVT Price | CheckOnChain | Network-value valuation discount/premium |
| 16 | VDD Multiple | CheckOnChain | Coin-days/velocity reset conditions |

Informational cards may also appear when data is available, such as **Long-Term Holder Supply** and **Pi Cycle Bottom**. These are displayed for context and are not included in the composite score.

## Score Interpretation

| Score | Assessment | Interpretation |
|-------|-----------|----------------|
| 80-100 | 🟢 Extreme Accumulation Zone | Broad capitulation/value conditions across active metrics |
| 65-79 | 🟢 Strong Accumulation Zone | Historically attractive long-term entry territory |
| 50-64 | 🟡 Moderate Opportunity | DCA-friendly, but not maximum-signal conditions |
| 35-49 | 🟡 Neutral | Mixed signals; not compelling either direction |
| 20-34 | 🔴 Caution — Overheated | Market conditions becoming less favorable |
| 0-19 | 🔴 Extreme Caution | Historically poor accumulation setup |

Backtest tables provide actual historical forward-return statistics per score bracket, including 30d/90d/180d/1yr averages, win rate, max gain/loss, and average max drawdown.

## ML-Optimized Scoring

The ML mode uses a `GradientBoostingClassifier` trained on historical feature rows to predict whether a day was a good long-term buy based on 365-day forward return. Training features include:

- Classic metric scores.
- Raw metric values.
- 30-day metric deltas.
- Interaction features such as MVRV × NUPL and Puell × Reserve Risk.
- Cycle-position context such as days since ATH.

The resulting feature importances are aggregated back into transparent metric weights stored in `config/ml_weights.json`. The UI displays normalized weight and contribution for each active metric.

Validation uses purged expanding time-series splits: because each label uses a 365-day forward-return window, training rows whose label windows overlap validation are removed before scoring validation folds.

## Tech Stack

| Component | Technology |
|-----------|-----------|
| Backend | Python 3.13 + FastAPI |
| Frontend | Inline HTML/CSS/JS dark trading-terminal UI |
| Charts | Chart.js |
| Scraping | requests + Playwright-style browser scraping where needed |
| Data APIs | alternative.me, CoinGecko, LookIntoBitcoin, CheckOnChain |
| ML | NumPy + pandas + scikit-learn GradientBoostingClassifier |
| Process Manager | pm2 or uvicorn |
| Default Port | 3088 |

## How Data Is Collected

Data is collected from free/public sources and cached locally under `data/`.

- Fast live refreshes update BTC price, ATH/drawdown, 200D SMA/Mayer where possible, and Fear & Greed.
- On-chain metrics are cached and reused because they update slowly.
- Full refresh re-scrapes on-chain metrics from LookIntoBitcoin/CheckOnChain.
- Historical backtest data lives in `data/history.json` and supports charting, backtests, and metric-context lookups.
- Score history appends to `data/score_history.jsonl`.

## Project Structure

```
├── dashboard/
│   └── server.py                  # FastAPI server + inline dashboard/backtest/settings UI
├── scrapers/
│   ├── lookintobitcoin.py         # LookIntoBitcoin metric scraping
│   ├── checkonchain.py            # CheckOnChain metric scraping
│   ├── history_collector.py       # Full historical data collection
│   ├── history_updater.py         # Incremental historical updates
│   ├── fear_greed.py              # Fear & Greed Index API
│   └── price.py                   # BTC price, ATH, drawdown, SMA helpers
├── scoring/
│   └── engine.py                  # Classic + ML-weighted scoring logic
├── backtesting/
│   └── engine.py                  # Historical backtest engine
├── ml/
│   └── optimizer.py               # ML training, purged CV, weight export
├── tests/
│   ├── test_ml_optimizer_validation.py
│   └── test_scoring_engine_ml.py
├── data/
│   ├── cache.json                 # Live metric cache
│   ├── history.json               # Historical metric/time-series data
│   └── score_history.jsonl        # Live score history
├── config/
│   ├── thresholds.json            # Classic scoring thresholds
│   ├── ml_weights.json            # Learned ML metric weights
│   └── llm_settings.json          # Optional AI commentary provider config
├── screenshots/                   # README screenshots
├── ARCHITECTURE.md
└── README.md
```

## Running

### Local / ad-hoc with uv

```bash
cd /opt/data/btc-accumulation-monitor
PYTHONPATH=. uv run \
  --with fastapi \
  --with uvicorn \
  --with requests \
  --with pandas \
  --with numpy \
  --with scikit-learn \
  python -m uvicorn dashboard.server:app --host 0.0.0.0 --port 3088
```

### VPS-style install

```bash
cd /opt/apps/btc-ml-optimizer
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements_vps.txt pandas numpy scikit-learn
python -m uvicorn dashboard.server:app --host 0.0.0.0 --port 3088
```

### pm2

```bash
pm2 start "python3 -m uvicorn dashboard.server:app --host 0.0.0.0 --port 3088" --name btc-ml-optimizer
```

## First Run

1. Visit `http://localhost:3088` for the live dashboard.
2. Use **Quick Refresh** for fast price/Fear & Greed updates.
3. Use **Full Refresh** to re-scrape on-chain metrics.
4. Visit `http://localhost:3088/backtest` to view historical score performance.
5. If historical data is missing, use the backtest page's collection flow to populate `data/history.json`.

## Useful API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /api/data?mode=classic` | Current metrics using equal-weight scoring |
| `GET /api/data?mode=ml` | Current metrics using ML-optimized weights |
| `GET /api/history` | Recent live score history |
| `POST /api/refresh` | Quick refresh |
| `POST /api/refresh?full=true` | Full on-chain refresh |
| `GET /api/backtest?mode=classic` | Historical backtest with classic scoring |
| `GET /api/backtest?mode=ml` | Historical backtest with ML scoring |
| `GET /api/metric-context?metric=mvrv_zscore&mode=ml` | Similar historical levels and forward returns for one metric |
| `GET /api/settings` | Safe LLM settings payload |

## Testing

Focused tests can be run with uv:

```bash
cd /opt/data/btc-accumulation-monitor
PYTHONPATH=. uv run --with pytest --with numpy --with scikit-learn --with pandas \
  pytest -q tests/test_ml_optimizer_validation.py tests/test_scoring_engine_ml.py
```

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for deeper implementation details on scoring, data collection, and backtesting.

## License

Private — not for public distribution.