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) <noreply@anthropic.com>

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:
 <http://localhost:9000/apidocs>.
+
+---
+
+## 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**: `<COIN>_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.