From 5ac9ebed5b8580af1d3f83a4c2f39523bfc47f15 Mon Sep 17 00:00:00 2001 From: Adriano Dal Pastro Date: Fri, 29 May 2026 07:51:47 +0000 Subject: [PATCH] docs: documenta discovery/validazione strumenti e gate del downloader 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) --- API_REFERENCE.md | 37 +++++++++++++++++++++++++++++++++++++ CLAUDE.md | 29 +++++++++++++++++++++++++++-- README.md | 23 +++++++++++++++++++++++ 3 files changed, 87 insertions(+), 2 deletions(-) diff --git a/API_REFERENCE.md b/API_REFERENCE.md index a0111f7..b810d8e 100644 --- a/API_REFERENCE.md +++ b/API_REFERENCE.md @@ -292,3 +292,40 @@ curl -X POST http://localhost:9000/mcp-bybit/tools/get_ticker \ Per lo schema completo dei body di richiesta e risposta: . + +--- + +## 15. Discovery strumenti — schemi `get_instruments` / `get_markets` / `get_historical` + +Schemi dei body verificati sull'OpenAPI live (usati da `src/data/instruments.py`). + +### Lista strumenti +| Exchange | Tool | Body | Risposta (campi utili) | +|---|---|---|---| +| Deribit | `get_instruments` | `{currency:"any", kind:"future", offset:int, limit:100}` (paginato, `has_more`) | `instruments[].name` (es. `BTC-PERPETUAL`, `SOL_USDC-PERPETUAL`), `expiry`, `tick_size` | +| Bybit | `get_instruments` | `{category:"linear", symbol?}` | `instruments[]`: `symbol`, `status`, `base_coin`, `quote_coin` | +| Hyperliquid | `get_markets` | `{}` | lista `{asset, mark_price, funding_rate, open_interest, volume_24h, max_leverage}` | + +### Storico OHLCV (`get_historical`, chiave `candles` uniforme `{timestamp(ms),open,high,low,close,volume}`) +| Exchange | Body | +|---|---| +| Deribit | `{instrument, start_date:"YYYY-MM-DD", end_date, resolution}` — resolution `1/5/15/60/1D` | +| Bybit | `{symbol, category:"linear", interval:"1/5/15/60/D", start:int_ms, end:int_ms, limit}` | +| Hyperliquid | `{asset|instrument, start_date, end_date, resolution:"1m/5m/15m/1h/1d", limit}` | + +### Simboli Deribit +- BTC/ETH → perpetui **inverse**: `BTC-PERPETUAL`, `ETH-PERPETUAL` +- Altcoin → perpetui **lineari USDC**: `_USDC-PERPETUAL` (es. `SOL_USDC-PERPETUAL`) +- Trappola: `LTC-PERPETUAL`/`ADA-PERPETUAL` non esistono; `SOL-PERPETUAL` esiste ma è un contratto sbagliato (prezzo ~9.6 vs SOL reale ~82). + +### Validazione (lato progetto) +`src/data/instruments.py` valida ogni strumento sui dati storici realmente +raccoglibili — esistenza, congruenza OHLC, not-flat, liquidità (volume daily) e +**congruenza prezzo cross-exchange** (scostamento dalla mediana del base-coin ≤5%). +Solo gli exchange con feed affidabile sono inclusi: **Deribit** e **Hyperliquid** +(esclusi Alpaca/stocks e **Bybit**, il cui feed testnet è farlocco). Output in +`data/instruments_registry.json`; il downloader scarica **solo** strumenti validati. + +> **Testnet.** Il token osservatore punta a testnet (`"testnet": true` nei ticker): +> i prezzi possono divergere dal mainnet. La congruenza cross-exchange via mediana +> è il filtro che scarta i feed incongrui prima di usarli per backtest/trading. diff --git a/CLAUDE.md b/CLAUDE.md index 28a9e40..6be5e2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,9 @@ Progetto di ricerca: riconoscimento pattern frattali per trading algoritmico su ## Struttura ``` -src/data/ → download e caricamento dati (downloader.py) +src/data/ → download e caricamento dati + downloader.py → download/caricamento parquet (gate: solo strumenti validati) + instruments.py → discovery + validazione strumenti per exchange, registry src/fractal/ → indicatori frattali (patterns.py, indicators.py, similarity.py) src/backtest/ → engine di backtesting (engine.py) src/strategies/ → classe base Strategy ABC + indicatori condivisi @@ -39,13 +41,15 @@ strategies.yml → config multi-strategy paper trader docs/diary/ → diario di ricerca giornaliero docs/specs/ → specifiche di design data/raw/ → file .parquet OHLCV (gitignored) +data/instruments_registry.json → allowlist strumenti validati (gate del downloader) ``` ## Comandi ```bash uv sync # installa dipendenze -uv run python -m src.data.downloader # scarica dati storici +uv run python -m src.data.downloader # scarica dati storici (solo strumenti validati) +uv run python -m src.data.instruments # (ri)costruisci il registry strumenti validati uv run python scripts/strategies/MR01_bollinger_fade.py # strategia attiva (mean-reversion) uv run python scripts/analysis/strategy_research.py # ricerca strategie fee-aware OOS uv run python scripts/analysis/oos_validation.py # perche' la famiglia squeeze e' scartata @@ -68,6 +72,27 @@ df = load_data("ETH", "15m") # carica un asset/timeframe Fonte primaria: Cerbero MCP (endpoint `/mcp-deribit/tools/get_historical`). Token observer: nel file `secrets/observer.token` del progetto CerberoSuite. +### Strumenti & validazione (gate raccolta dati) + +`src/data/instruments.py` scopre e **valida** gli strumenti per ogni exchange +implementato — **Deribit** e **Hyperliquid** (esclusi Alpaca/stocks e **Bybit**, +il cui feed testnet è farlocco). Per ogni perpetuo enumera via `get_instruments` +/`get_markets` e verifica sui **dati storici realmente raccoglibili**: +esistenza, congruenza OHLC, not-flat (scarta contratti morti), liquidità (volume +daily) e **congruenza prezzo cross-exchange** (scostamento dalla mediana del +base-coin ≤ 5% → scarta outlier come `SOL-PERPETUAL`=9.6 vs SOL reale ~82). + +Output: `data/instruments_registry.json` (strumenti validi, timeframe, start-date). +**Gate:** `_download_cerbero_range` rifiuta gli strumenti non validati (override +`allow_unvalidated=True` solo per casi eccezionali). Rigenera con +`python -m src.data.instruments`. + +> **NB testnet.** Il token Cerbero punta a testnet; la congruenza cross-exchange +> è il filtro che distingue i feed realistici (Deribit, Hyperliquid) da quelli +> farlocchi (Bybit). Simboli Deribit: BTC/ETH = `-PERPETUAL` (inverse); +> alt = `_USDC-PERPETUAL` (lineari USDC). Registry attuale: Deribit 18/106, +> Hyperliquid 66/74 validi (major liquidi: BTC dal 2018, alt dal 2022). + ## Strategie attive > **LEZIONE CRITICA (2026-05-28).** L'intera famiglia squeeze-breakout (SQ01-04, diff --git a/README.md b/README.md index 056e41b..2c79097 100644 --- a/README.md +++ b/README.md @@ -198,9 +198,32 @@ uv run python -m src.live.multi_runner |-------|-----------|---------|-----------| | 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 = `-PERPETUAL` (inverse); altcoin = +`_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)