Adriano Dal Pastro
5ac9ebed5b
CLAUDE.md, README.md, API_REFERENCE.md aggiornati per il nuovo layer src/data/instruments.py: validazione strumenti per exchange (Deribit + Hyperliquid; esclusi Alpaca e Bybit testnet), congruenza prezzo cross-exchange, registry come allowlist, gate nel downloader. Aggiunti schemi param get_instruments/get_markets/get_historical per exchange e convenzione simboli Deribit (inverse vs USDC lineari). Universo dati esteso con SOL/LTC/ADA 1h. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
235 lines
9.4 KiB
Markdown
235 lines
9.4 KiB
Markdown
# PythagorasGoal
|
||
|
||
Sistema di riconoscimento pattern frattali e predizione per il trading di criptovalute (BTC, ETH), ispirato al framework teorico di Serleto & Malanga (*Pythagoras Trading Prediction*).
|
||
|
||
## Obiettivo
|
||
|
||
Partendo da un capitale iniziale di €1.000, raggiungere un profitto medio di €50 al giorno entro 6–8 mesi, tramite strategie algoritmiche che combinano analisi frattale, squeeze di volatilità e machine learning.
|
||
|
||
## Risultati
|
||
|
||
> ⚠️ **Revisione 2026-05-28.** La famiglia squeeze-breakout (SQ/MT/ML/AD/CM/PD, con
|
||
> accuracy storiche dichiarate 76-82%) è stata **scartata**: quei numeri erano un
|
||
> **artefatto di look-ahead**. I backtest decidevano la direzione dalla candela di
|
||
> breakout `close[i]` ma entravano a `close[i-1]` — impossibile dal vivo. Sotto
|
||
> ingresso onesto (`close[i]`) e fee reali, l'edge sparisce e tutte perdono, anche
|
||
> a fee zero. Dettagli e prove: `scripts/analysis/oos_validation.py`.
|
||
|
||
Dopo una validazione **out-of-sample, fee-aware** di tutte le famiglie, l'unica con
|
||
edge netto reale è il **mean-reversion** (i breakout *rientrano*, non continuano):
|
||
|
||
| Codice | Strategia | Mercato | Edge OOS netto | Max DD | Robustezza |
|
||
|--------|-----------|---------|----------------|--------|------------|
|
||
| **MR01** | Bollinger Fade (mean-reversion) | BTC 1h | **+196 / +201%** | 15% | ✅ |
|
||
| **MR01** | Bollinger Fade (mean-reversion) | ETH 1h | **+251%** | ~25% | ⚠️ DD alto |
|
||
|
||
Netto dopo **fee realistiche Deribit 0.10% RT** (taker), leva 3x, pos 15%, su finestra
|
||
held-out (nov 2023→mag 2026). MR01 è positivo su **tutta** la griglia parametri
|
||
(`n∈{14,20,30,50}` × `k∈{2.0,2.5,3.0}`) e per **ogni** livello di fee 0.00-0.20% RT —
|
||
margine di sicurezza ampio, niente parametro fortunato. Ri-validato col worker live reale.
|
||
|
||
## Come funziona
|
||
|
||
### MR01 — Bollinger Fade (mean-reversion)
|
||
|
||
La strategia attiva sfrutta il fatto, emerso dai dati, che su BTC/ETH a 1h gli estremi
|
||
di prezzo **rientrano verso la media** più di quanto proseguano:
|
||
|
||
1. **Bollinger Bands** (window `n`, `k` deviazioni standard) sul close.
|
||
2. **Entry** — quando il close esce *sotto* la banda inferiore → **long** (o *sopra* la superiore → **short**). Ingresso a `close[i]`, eseguibile dal vivo.
|
||
3. **Take-profit** alla media mobile (il rientro atteso).
|
||
4. **Stop-loss** a `sl_atr × ATR` oltre l'estremo; **time-limit** a `max_bars`.
|
||
|
||
Nessun look-ahead: direzione e livelli sono calcolati con dati fino a `close[i]`.
|
||
|
||
### Perché lo squeeze breakout è stato abbandonato
|
||
|
||
L'ipotesi originale era opposta — *continuazione* dopo la compressione di volatilità
|
||
(Bollinger dentro Keltner → breakout direzionale). Su dati storici sembrava dare
|
||
76-82% di accuracy, ma era un **artefatto di look-ahead**: il backtest entrava a
|
||
`close[i-1]` con direzione decisa da `close[i]`. Replicando l'esecuzione reale
|
||
(ingresso a `close[i]`) l'edge collassa al ~47% (lancio di moneta) e i costi fanno
|
||
il resto. Il test sui breakout intra-barra a 5m conferma che il movimento *rientra*
|
||
subito (mean-reversion), giustificando MR01. Tutta la famiglia squeeze è in `scripts/waste/`.
|
||
|
||
### Lezione metodologica
|
||
|
||
Ogni nuova strategia deve passare: (1) **ingresso eseguibile** senza look-ahead,
|
||
(2) backtest **netto** dopo fee realistiche (0.10% RT Deribit), (3) validazione
|
||
**out-of-sample** + robustezza su griglia parametri + sweep fee. Strumenti in
|
||
`scripts/analysis/` (`strategy_research.py`, `oos_validation.py`, `intrabar_test.py`).
|
||
|
||
## Struttura progetto
|
||
|
||
```
|
||
PythagorasGoal/
|
||
├── src/
|
||
│ ├── data/ # Download e gestione dati (Cerbero MCP + Binance)
|
||
│ ├── fractal/ # Indicatori frattali: Hurst, Higuchi FD, self-similarity
|
||
│ ├── backtest/ # Motore di backtesting con fee e metriche
|
||
│ ├── strategies/ # Classe base Strategy ABC + indicatori condivisi
|
||
│ │ ├── base.py # Strategy, Signal, BacktestResult, YearlyStats
|
||
│ │ └── indicators.py # keltner_ratio, detect_squeezes, ema, atr, rv, corr
|
||
│ └── live/ # Paper trading live su Deribit testnet
|
||
│ ├── multi_runner.py # Orchestratore multi-strategia
|
||
│ ├── strategy_worker.py # Worker indipendente con stato persistente
|
||
│ ├── strategy_loader.py # Import dinamico classi Strategy
|
||
│ ├── cerbero_client.py # Client HTTP per Cerbero MCP
|
||
│ ├── signal_engine.py # Squeeze + ML real-time (legacy) + validazione OOS
|
||
│ └── telegram_notifier.py
|
||
├── scripts/
|
||
│ ├── strategies/ # Strategie con edge validato OOS (solo MR01_bollinger_fade)
|
||
│ ├── waste/ # Strategie scartate (W01-W28 + famiglia squeeze SQ/MT/ML/AD/CM/PD)
|
||
│ └── analysis/ # Ricerca/validazione OOS fee-aware (strategy_research, oos_validation, ...)
|
||
├── strategies.yml # Config multi-strategy paper trader
|
||
├── data/
|
||
│ └── raw/ # Parquet OHLCV (gitignored, ~70 MB)
|
||
├── docs/
|
||
│ ├── diary/ # Diario di ricerca giornaliero
|
||
│ └── specs/ # Specifiche di design
|
||
├── Dockerfile
|
||
├── docker-compose.yml
|
||
└── pyproject.toml
|
||
```
|
||
|
||
## Strategie attive
|
||
|
||
Tutte le strategie estendono `src.strategies.base.Strategy` (`generate_signals() → backtest()`).
|
||
|
||
| Codice | Script | Tipo | Descrizione |
|
||
|--------|--------|------|-------------|
|
||
| **MR01** | `MR01_bollinger_fade.py` | Mean-reversion | Fada la banda di Bollinger, TP alla media, SL ad ATR. Unica con edge netto validato OOS. |
|
||
|
||
La famiglia squeeze (SQ01-04, ML01, MT01, PD01, CM01, AD01) è in `scripts/waste/`:
|
||
edge storico = artefatto di look-ahead (vedi sezione *Come funziona*).
|
||
|
||
Per eseguire il backtest della strategia:
|
||
|
||
```bash
|
||
uv run python scripts/strategies/MR01_bollinger_fade.py
|
||
```
|
||
|
||
Per la ricerca/validazione fee-aware out-of-sample:
|
||
|
||
```bash
|
||
uv run python scripts/analysis/strategy_research.py # screening famiglie + deep-dive MR01
|
||
uv run python scripts/analysis/oos_validation.py # perche' la famiglia squeeze e' scartata
|
||
uv run python scripts/analysis/validate_worker_mr01.py # replay del worker live su MR01
|
||
```
|
||
|
||
## Paper Trading Live
|
||
|
||
Il multi-strategy runner esegue N strategie in parallelo su dati live da Cerbero MCP, ognuna con €1000 USDC virtuali indipendenti. Se un `Signal` porta `tp`/`sl`/`max_bars` in `metadata` (come MR01), il worker chiude su take-profit alla media / stop-loss ad ATR / time-limit; altrimenti usa il fallback `hold_bars`/stop -2%.
|
||
|
||
### Avvio
|
||
|
||
```bash
|
||
# Locale
|
||
uv run python -m src.live.multi_runner
|
||
|
||
# Docker
|
||
docker compose up -d
|
||
```
|
||
|
||
### Configurazione
|
||
|
||
Le strategie attive sono definite in `strategies.yml`:
|
||
|
||
```yaml
|
||
defaults:
|
||
capital: 1000
|
||
position_size: 0.15
|
||
leverage: 3
|
||
|
||
strategies:
|
||
- name: MR01_bollinger_fade
|
||
asset: BTC
|
||
tf: 1h
|
||
enabled: true
|
||
params:
|
||
bb_window: 50
|
||
k: 2.5
|
||
sl_atr: 2.0
|
||
max_bars: 24
|
||
```
|
||
|
||
Per aggiungere una strategia: nuova riga in `strategies.yml`, poi `docker compose restart`. Lo storico delle strategie esistenti rimane intatto.
|
||
|
||
### Persistenza
|
||
|
||
Ogni strategia ha la sua directory in `data/paper_trades/`:
|
||
|
||
```
|
||
data/paper_trades/
|
||
MR01_bollinger_fade__BTC__1h/
|
||
trades.jsonl # Storico trade append-only
|
||
status.json # Stato corrente (resume al restart, include tp/sl/max_bars)
|
||
```
|
||
|
||
Notifiche Telegram per ogni trade (richiede `TELEGRAM_BOT_TOKEN` e `TELEGRAM_CHAT_ID` in `.env`).
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
# Clona e installa
|
||
git clone <repo-url> && cd PythagorasGoal
|
||
uv sync
|
||
|
||
# Scarica dati storici (~70 MB)
|
||
uv run python -m src.data.downloader
|
||
|
||
# Backtest strategia attiva
|
||
uv run python scripts/strategies/MR01_bollinger_fade.py
|
||
|
||
# Paper trading live
|
||
uv run python -m src.live.multi_runner
|
||
```
|
||
|
||
### Requisiti
|
||
|
||
- Python ≥ 3.11
|
||
- [uv](https://docs.astral.sh/uv/) come package manager
|
||
- Accesso a Cerbero MCP (`cerbero-mcp.tielogic.xyz`) per dati Deribit live
|
||
- Docker (opzionale, per deploy su VPS)
|
||
|
||
## Dati
|
||
|
||
| Asset | Timeframe | Candele | Copertura |
|
||
|-------|-----------|---------|-----------|
|
||
| BTC | 5m / 15m / 1h | 883K / 294K / 74K | 2018-01 → oggi |
|
||
| ETH | 5m / 15m / 1h | 882K / 294K / 74K | 2018-01 → oggi |
|
||
| SOL / LTC / ADA | 1h | ~37K each | 2022 → oggi |
|
||
|
||
Fonte primaria: Deribit perpetual via Cerbero MCP. Fallback: Binance spot via ccxt. Formato: Apache Parquet.
|
||
|
||
### Discovery & validazione strumenti
|
||
|
||
`src/data/instruments.py` scopre e **valida** gli strumenti disponibili sugli
|
||
exchange implementati — **Deribit** e **Hyperliquid** (esclusi Alpaca/stocks e
|
||
**Bybit**, feed testnet inaffidabile). Ogni perpetuo viene testato sui dati
|
||
storici realmente raccoglibili: esistenza, congruenza OHLC, contratto non-morto,
|
||
liquidità e **congruenza prezzo cross-exchange** (mediana per base-coin, tolleranza
|
||
5%) — così feed farlocchi e contratti sbagliati (es. `SOL-PERPETUAL`=9.6) vengono
|
||
scartati. Il risultato è `data/instruments_registry.json` (strumenti validi +
|
||
timeframe + data d'inizio).
|
||
|
||
**Solo gli strumenti validati possono essere scaricati**: il downloader ha un gate
|
||
(`_download_cerbero_range`) che rifiuta quelli non nel registry. Rigenera con:
|
||
|
||
```bash
|
||
uv run python -m src.data.instruments
|
||
```
|
||
|
||
Simboli Deribit: BTC/ETH = `<COIN>-PERPETUAL` (inverse); altcoin =
|
||
`<COIN>_USDC-PERPETUAL` (lineari USDC). Registry attuale (testnet): Deribit 18/106
|
||
validi (major liquidi, BTC dal 2018), Hyperliquid 66/74.
|
||
|
||
## Riferimenti
|
||
|
||
- Serleto, L. & Malanga, C. — *Pythagoras Trading Prediction* (2024)
|
||
- Serleto, L. & Malanga, C. — *Libro dei Frattali* (2024)
|
||
|
||
## Licenza
|
||
|
||
Uso privato. Non destinato alla distribuzione.
|