btc-accumulation-monitor/ARCHITECTURE.md

Bitcoin Accumulation Zone Monitor — Architecture & Logic

Overview

This is NOT a trading bot or ML predictor. It monitors proven Bitcoin on-chain metrics that have historically signaled optimal accumulation (buying) zones for long-term holders. Each metric scores 0-10 points, producing a composite score of 0-100.

Philosophy: Every signal is transparent and traceable. No black box. The metrics used have correctly identified every major Bitcoin cycle bottom since 2010.

How It Works

Data Pipeline

LookIntoBitcoin.com ──┐
  (Playwright scraper) │
                       ├──> data/cache.json (current values, refreshed every 15min)
alternative.me API ────┤    data/history.json (full history back to 2010, refreshed weekly)
                       │
CoinGecko API ─────────┘
         │
         ▼
   Scoring Engine (scoring/engine.py)
         │
         ▼
   Composite Score 0-100
         │
    ┌────┴────┐
    ▼         ▼
 Dashboard   Backtest Engine
 (live)      (historical validation)

Data Sources

All data is scraped or fetched from free sources — no API keys required.

Source	Method	Data
LookIntoBitcoin / BitcoinMagazinePro	Playwright browser scraping of Plotly Dash charts	Puell Multiple, MVRV Z-Score, Reserve Risk, RHODL Ratio, NUPL, 200W SMA, LTH Realized Price, LTH Supply, Hash Ribbons, Pi Cycle
alternative.me	Free REST API	Fear & Greed Index (daily, back to Feb 2018)
CoinGecko	Free REST API	BTC price, market cap, 24h change

Scraping Method (LookIntoBitcoin)

The site uses Plotly Dash charts. We intercept the _dash-update-component XHR response which contains the full chart data as JSON:

page.on("response", handler)  # Intercept XHR
page.goto("https://www.lookintobitcoin.com/charts/puell-multiple/")
# Response contains: response['chart']['figure']['data'] → list of trace objects
# Each trace: {name: str, x: [dates], y: [values]}

This gives us the complete historical time series (5000+ data points per metric going back to 2010) without needing any API key.

Scoring System

Individual Metrics (0-10 each)

1. Fear & Greed Index (source: alternative.me)

Measures market sentiment from social media, surveys, and momentum.

F&G Value	Classification	Score
0-10	Extreme Fear	10
11-25	Fear	7
26-45	Neutral-low	4
46-55	Neutral	2
56-75	Greed	1
76-100	Extreme Greed	0

Logic: "Be fearful when others are greedy, be greedy when others are fearful." — Buffett. Extreme Fear has historically coincided with cycle bottoms.

2. Puell Multiple (source: LookIntoBitcoin)

Measures miner revenue relative to 365-day average. When miners earn very little (low Puell), they're capitulating — historically a bottom signal.

Puell Value	Meaning	Score
< 0.3	Deep miner capitulation	10
0.3-0.5	Miner stress	8
0.5-0.8	Below average revenue	5
0.8-1.2	Normal	3
1.2-2.0	Above average	1
> 2.0	Miner euphoria	0

Historical accuracy: Puell < 0.5 identified the Dec 2018, Mar 2020, and Jun 2022 bottoms.

3. MVRV Z-Score (source: LookIntoBitcoin)

Compares market value to realized value. Negative Z-Score means the market is valued below what everyone paid — extreme undervaluation.

Z-Score	Meaning	Score
< 0	Below realized value	10
0-0.5	Undervalued	8
0.5-1.5	Fair value	5
1.5-3.0	Overvalued	2
3.0-5.0	Very overvalued	1
> 5.0	Extreme overvaluation	0

Historical accuracy: Every time MVRV Z-Score went below 0, buying led to >200% returns within 2 years (100% hit rate across all cycles).

4. Drawdown from ATH (calculated from price)

How far BTC has fallen from its all-time high. Larger drawdowns = better buying opportunity historically.

Drawdown	Score
> 70%	10
50-70%	8
30-50%	6
20-30%	4
10-20%	2
< 10%	0

5. Price vs 200-Week SMA (source: LookIntoBitcoin)

The 200-week moving average has historically acted as the absolute floor in bear markets.

Position	Score
Below 200W SMA	10
0-20% above	6
20-50% above	3
50-100% above	1
> 100% above	0

6. Reserve Risk (source: LookIntoBitcoin)

Measures the confidence of long-term holders relative to the price. Low Reserve Risk = high confidence among HODLers + low price = excellent time to buy.

Reserve Risk	Score
< 0.002	10
0.002-0.005	7
0.005-0.01	4
0.01-0.02	2
> 0.02	0

7. RHODL Ratio (source: LookIntoBitcoin)

Ratio of 1-week old coins to 1-2 year old coins. Low ratio = long-term holders dominating (accumulation). High ratio = short-term speculation (distribution).

RHODL	Score
< 100	10
100-500	7
500-2000	4
2000-10000	1
> 10000	0

8. NUPL — Net Unrealized Profit/Loss (source: LookIntoBitcoin)

Shows what fraction of market cap is unrealized profit. Negative = market is at a loss (capitulation). Above 0.75 = euphoria.

NUPL	Phase	Score
< 0	Capitulation	10
0-0.25	Hope/Fear	7
0.25-0.5	Optimism	4
0.5-0.75	Belief/Greed	1
> 0.75	Euphoria	0

9. LTH Realized Price vs Spot (source: LookIntoBitcoin)

Long-Term Holder Realized Price = average cost basis of coins held >155 days. When spot price drops below this, even diamond hands are underwater — extreme value.

Position	Score
Price below LTH RP	10
0-20% above	6
20-50% above	3
> 50% above	1

10. Hash Ribbons / Miner Capitulation (source: LookIntoBitcoin)

When miners capitulate (hash rate declining), it signals maximum pain. The recovery signal (hash rate resuming growth) has been a reliable buy signal.

Signal	Score
Active buy signal	10
Recent recovery	6
Normal	3
Miner euphoria	0

Composite Score

Total Score = Sum of all individual metric scores (0-100)

Score Range	Assessment	Action
85-100	Extreme Accumulation Zone	Strong buy — historically rare, ~4x per decade
70-84	Strong Accumulation	Buy — excellent long-term entry
55-69	Moderate Opportunity	Consider buying — decent entry
40-54	Neutral	Hold — not compelling either way
25-39	Caution	Reduce or wait — market heating up
0-24	Extreme Caution	Do NOT buy — historically the worst times

Backtest Engine

Purpose

Reconstruct the composite score historically and compare against actual BTC forward returns to validate the scoring system's accuracy.

Methodology

1. Historical Reconstruction: Using scraped historical data (2010-present), calculate what each metric's score would have been on every day
2. Forward Returns: For each historical day, calculate what BTC actually returned over the next 30, 90, 180, and 365 days
3. Score Bracket Analysis: Group days by score bracket and calculate average forward returns, win rates, max drawdowns
4. Recency Weighting: More recent cycles weighted higher because BTC's cycle-over-cycle returns diminish as it matures:
   • 2022-present: 4x weight
   • 2020-2021: 3x weight
   • 2018-2019: 2x weight
   • Before 2018: 1x weight
5. Cycle-Separated Results: Returns shown per cycle (Cycle 3: 2016-2019, Cycle 4: 2020-2023, Cycle 5: 2024+)

Diminishing Returns Adjustment

Bitcoin's gains decrease every cycle. A score of 90 in 2018 led to different outcomes than a score of 90 in 2022:

• The backtest separates results by cycle
• Current expectations are based on the 2 most recent comparable cycles
• Adaptive thresholds recalculate based on rolling 2-year windows

Architecture

/opt/apps/btc-ml-optimizer/
├── dashboard/
│   └── server.py              # FastAPI + inline HTML/JS dashboard
├── scrapers/
│   ├── __init__.py
│   ├── lookintobitcoin.py     # Playwright scraper for on-chain charts
│   ├── history_collector.py   # Full historical data collection
│   ├── fear_greed.py          # alternative.me Fear & Greed API
│   └── price.py               # CoinGecko BTC price API
├── scoring/
│   ├── __init__.py
│   └── engine.py              # Scoring logic and thresholds
├── backtesting/
│   ├── __init__.py
│   └── engine.py              # Historical backtest calculations
├── data/
│   ├── cache.json             # Current metric values (refreshed every 15min)
│   └── history.json           # Full historical data (refreshed weekly)
├── config/
│   ├── thresholds.json        # Configurable scoring thresholds
│   └── llm_settings.json      # Optional LLM provider config for AI commentary
├── llm_client/
│   └── analyzer.py            # Optional LLM integration for signal analysis
└── README.md

Infrastructure

• Server: Main VPS (Hostinger), Tailscale IP 100.94.106.120
• Port: 3088
• Process Manager: pm2 (btc-ml-optimizer)
• Dashboard URL: http://100.94.106.120:3088
• Backtest URL: http://100.94.106.120:3088/backtest
• Git Repo: https://git.bizzle.lol/bizzle/btc-accumulation-monitor

Dependencies

• Python 3.13
• FastAPI + uvicorn
• Playwright (Chromium, headless)
• requests
• No ML libraries required
• No paid API keys required