feat(games): sessioni 2-3 Blind Traders (opzioni/session/grid) + gate PORT06 e tooling reset
- Gioco GRID TRADERS (sessione 3, regola STRATEGIA_GRIGLIA.md): grid_engine (backtest causale fee-aware della griglia geometrica), grid_brief (digest anonimo per dimensionare la griglia), grid_arena (torneo 100 agenti); diario docs/diary/2026-06-10-grid-traders-game3.md - Gioco OPZIONI: options_engine (BS + skew fittato + DVOL storica), options_arena, opt_calibrate (superficie premi REALE da cerbero-bite) - Gioco SESSION: session_engine/session_arena (pattern orari intraday) - arena: vincolo GAME_NO_LIVE=1 (vieta pairs e fade zscore/breakout/momentum gia' live, coercizione a trend/ma_cross) + normalize del candidato PRIMA della valutazione nel hill-climb - Gate: grid_game_gate (griglia ETH vincitrice vs PORT06, mark-to-market), pairs30m_gate (ETH/BTC 30m ridondante col 15m gia' deployato?) - reset_flatten: flatten one-shot del conto testnet per il reset portafoglio - .gitignore: data/portfolio_paper_stats/ (stato runtime sleeve paper-only) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Adriano Dal Pastro
@@ -0,0 +1,212 @@
|
||||
# Strategia di Grid Trading — Versione Corretta
|
||||
|
||||
> Documento di specifica della strategia. Descrive *cosa* deve fare il bot e *perché*,
|
||||
> non l'implementazione. È il riferimento da cui partire per riscrivere il codice in
|
||||
> modo sicuro e testabile.
|
||||
|
||||
---
|
||||
|
||||
## 1. Obiettivo
|
||||
|
||||
Estrarre profitto dalla **volatilità di un asset all'interno di un intervallo di prezzo
|
||||
(range)**, comprando automaticamente quando il prezzo scende e vendendo quando risale,
|
||||
secondo livelli predefiniti (la "griglia").
|
||||
|
||||
La griglia **non prevede** la direzione del mercato: monetizza le oscillazioni. Funziona
|
||||
quando il prezzo oscilla; perde quando il prezzo prende un trend deciso. Tutta la
|
||||
progettazione che segue serve a massimizzare il primo caso e a limitare i danni nel
|
||||
secondo.
|
||||
|
||||
---
|
||||
|
||||
## 2. Principi corretti (cosa cambia rispetto al bot originale)
|
||||
|
||||
| Aspetto | Bot originale (sbagliato) | Versione corretta |
|
||||
|---|---|---|
|
||||
| Asset | Shitcoin illiquida (LAND) | Coppia liquida (es. ETH/USDT, BNB/USDT) |
|
||||
| Passo griglia | Assoluto in USDT (`GRID_STEP=3`) | **Percentuale** sul prezzo |
|
||||
| Livelli | Mobili, inseguono il prezzo | **Fissi** dentro un range definito |
|
||||
| Protezione perdite | Nessuna | **Stop-loss** sotto il range + **take-profit** sopra |
|
||||
| Slippage | `amountOutMin = 0` (nessuna) | Calcolato da `getAmountsOut` − tolleranza |
|
||||
| Break-even fee | Ignorato | Passo griglia **> costo round-trip** |
|
||||
| Capitale | Tutto, senza limiti | Allocazione fissa, suddivisa per livello |
|
||||
| Chiave privata | In chiaro nel `.env` | Keystore cifrato o input a runtime |
|
||||
| Validazione | Nessuna | **Backtest** + **testnet** prima del capitale reale |
|
||||
|
||||
---
|
||||
|
||||
## 3. Definizione della griglia
|
||||
|
||||
### 3.1 Parametri di ingresso
|
||||
|
||||
| Parametro | Significato | Esempio |
|
||||
|---|---|---|
|
||||
| `PAIR` | Coppia da tradare (base/quote) | `ETH/USDT` |
|
||||
| `RANGE_LOW` | Estremo inferiore del range | `2800` |
|
||||
| `RANGE_HIGH` | Estremo superiore del range | `3400` |
|
||||
| `GRID_LEVELS` | Numero di livelli nella griglia | `12` |
|
||||
| `CAPITAL_QUOTE` | Capitale totale in quote (USDT) | `1200` |
|
||||
| `STOP_LOSS` | Prezzo sotto cui il bot chiude tutto e si ferma | `2650` |
|
||||
| `TAKE_PROFIT` | Prezzo sopra cui il bot chiude tutto e si ferma | `3550` |
|
||||
| `SLIPPAGE_BPS` | Tolleranza slippage in basis point (50 = 0,5%) | `50` |
|
||||
| `FEE_BPS` | Fee del DEX in basis point (PancakeSwap = 25) | `25` |
|
||||
|
||||
### 3.2 Costruzione dei livelli (griglia geometrica)
|
||||
|
||||
I livelli vanno spaziati in **percentuale**, non in valore assoluto. Una griglia
|
||||
geometrica mantiene lo stesso rendimento percentuale per ogni gradino, indipendentemente
|
||||
dal prezzo.
|
||||
|
||||
```
|
||||
ratio = (RANGE_HIGH / RANGE_LOW) ^ (1 / GRID_LEVELS)
|
||||
livello[i] = RANGE_LOW * ratio ^ i per i = 0 .. GRID_LEVELS
|
||||
```
|
||||
|
||||
Esempio (`RANGE_LOW=2800`, `RANGE_HIGH=3400`, `GRID_LEVELS=12`):
|
||||
`ratio ≈ 1,0163` → passo di circa **1,63% per gradino**.
|
||||
|
||||
### 3.3 Capitale per livello
|
||||
|
||||
```
|
||||
quote_per_livello = CAPITAL_QUOTE / GRID_LEVELS
|
||||
```
|
||||
|
||||
Ogni livello di acquisto impegna `quote_per_livello`. Il capitale è suddiviso in anticipo:
|
||||
il bot **non** può comprare più di quanto allocato, e non scende mai sotto zero.
|
||||
|
||||
---
|
||||
|
||||
## 4. Vincolo di break-even (regola anti-fee)
|
||||
|
||||
Una griglia con passi troppo fitti perde: le fee di ogni round-trip (compra + vendi) si
|
||||
mangiano il profitto. **Il passo percentuale della griglia deve superare il costo totale
|
||||
di un round-trip.**
|
||||
|
||||
```
|
||||
costo_round_trip ≈ 2 * (FEE_BPS + SLIPPAGE_BPS) / 10000 (in frazione)
|
||||
passo_griglia = ratio - 1
|
||||
|
||||
VINCOLO: passo_griglia > costo_round_trip * margine_sicurezza (margine ≥ 1,5)
|
||||
```
|
||||
|
||||
Esempio con `FEE_BPS=25`, `SLIPPAGE_BPS=50`:
|
||||
`costo_round_trip ≈ 2 * (25+50)/10000 = 1,5%`. Con margine 1,5 → il passo deve essere
|
||||
**≥ 2,25%**. Se la griglia geometrica dà 1,63%, **è troppo fitta**: vanno ridotti i
|
||||
`GRID_LEVELS` o allargato il range finché il vincolo è rispettato. Il bot deve rifiutarsi
|
||||
di partire se il vincolo non è soddisfatto.
|
||||
|
||||
---
|
||||
|
||||
## 5. Logica operativa
|
||||
|
||||
### 5.1 Inizializzazione
|
||||
1. Validare i parametri: `RANGE_LOW < prezzo_attuale < RANGE_HIGH`, vincolo di break-even
|
||||
rispettato, capitale disponibile sul wallet.
|
||||
2. Verificare la coppia: liquidità sufficiente, contratto non honeypot (controllo
|
||||
obbligatorio, non opzionale), token con decimali noti.
|
||||
3. Costruire i livelli (§3.2) e marcare ognuno come `attivo`/`riempito`.
|
||||
4. Allocare il capitale (§3.3).
|
||||
|
||||
### 5.2 Ciclo principale
|
||||
A ogni tick (es. ogni nuovo blocco, o ogni N secondi):
|
||||
|
||||
```
|
||||
prezzo = prezzo_corrente(PAIR)
|
||||
|
||||
# --- guardie di uscita: hanno priorità su tutto ---
|
||||
SE prezzo <= STOP_LOSS:
|
||||
vendi_tutta_la_posizione() # con slippage protetto
|
||||
ferma il bot, log "STOP-LOSS"
|
||||
SE prezzo >= TAKE_PROFIT:
|
||||
vendi_tutta_la_posizione()
|
||||
ferma il bot, log "TAKE-PROFIT"
|
||||
|
||||
# --- logica griglia ---
|
||||
PER ogni livello L:
|
||||
SE prezzo attraversa L verso il basso E L non è ancora riempito:
|
||||
compra quote_per_livello # con amountOutMin protetto
|
||||
marca L come riempito
|
||||
SE prezzo attraversa L verso l'alto E il livello sotto è riempito:
|
||||
vendi la quantità di quel livello # con amountOutMin protetto
|
||||
marca quel livello come libero
|
||||
```
|
||||
|
||||
I livelli sono **fissi** (calcolati una volta), non inseguono il prezzo. Questo rende il
|
||||
comportamento prevedibile e backtestabile.
|
||||
|
||||
### 5.3 Calcolo `amountOutMin` (protezione slippage — obbligatoria)
|
||||
|
||||
Mai passare `0`. Prima di ogni swap:
|
||||
|
||||
```
|
||||
atteso = router.getAmountsOut(amountIn, path)[ultimo]
|
||||
amountOutMin = atteso * (10000 - SLIPPAGE_BPS) / 10000
|
||||
```
|
||||
|
||||
Se la transazione non rientra nella tolleranza, deve **fallire** (revert), non eseguire a
|
||||
qualsiasi prezzo.
|
||||
|
||||
---
|
||||
|
||||
## 6. Gestione del rischio
|
||||
|
||||
1. **Stop-loss obbligatorio** sotto `RANGE_LOW`. È la differenza tra "strategia" e
|
||||
"gambling": senza stop-loss un trend ribassista svuota il wallet.
|
||||
2. **Take-profit** sopra `RANGE_HIGH` per chiudere quando il prezzo esce dal range al
|
||||
rialzo (la griglia avrebbe già venduto tutto; il take-profit evita di restare esposti).
|
||||
3. **Capitale segregato**: usare un wallet dedicato, con solo il capitale destinato alla
|
||||
strategia. Mai il wallet principale.
|
||||
4. **Limite di gas e prezzo gas** ragionevoli, ricalcolati dinamicamente (no valori fissi
|
||||
obsoleti).
|
||||
5. **Kill-switch manuale**: comando per fermare il bot e liquidare in qualsiasi momento.
|
||||
6. **Idempotenza/recupero**: se il bot si riavvia, deve ricostruire lo stato dei livelli
|
||||
(riempiti/liberi) dal saldo on-chain, non ripartire da zero.
|
||||
|
||||
---
|
||||
|
||||
## 7. Validazione prima del capitale reale
|
||||
|
||||
Nessun fondo reale prima di aver superato, in ordine:
|
||||
|
||||
1. **Backtest** su dati storici della coppia (almeno alcuni mesi, includendo sia fasi
|
||||
laterali sia un trend marcato), misurando: PnL netto **dopo** fee e slippage,
|
||||
max drawdown, numero di trade, comportamento allo stop-loss.
|
||||
2. **Paper trading / simulazione** in tempo reale, senza eseguire ordini veri.
|
||||
3. **Testnet** (BSC testnet) con la stessa logica e router di test, per verificare
|
||||
l'esecuzione on-chain end-to-end.
|
||||
4. **Mainnet con capitale minimo** (es. l'equivalente di pochi euro) per la prima
|
||||
settimana, poi scalare solo se i risultati combaciano col backtest.
|
||||
|
||||
---
|
||||
|
||||
## 8. Quando NON usare questa strategia
|
||||
|
||||
- Asset illiquido o a rischio rug-pull/honeypot.
|
||||
- Mercato in trend forte e prolungato (la griglia perde: lo stop-loss limita il danno ma
|
||||
non genera profitto).
|
||||
- Passo griglia che non rispetta il vincolo di break-even (§4).
|
||||
- Capitale che non puoi permetterti di perdere.
|
||||
|
||||
---
|
||||
|
||||
## 9. Parametri di esempio (configurazione di partenza prudente)
|
||||
|
||||
```
|
||||
PAIR = BNB/USDT # coppia liquida su PancakeSwap
|
||||
RANGE_LOW = 580
|
||||
RANGE_HIGH = 720
|
||||
GRID_LEVELS = 8 # passo ≈ 2,7% > break-even
|
||||
CAPITAL_QUOTE = 400 # USDT, su wallet dedicato
|
||||
STOP_LOSS = 545 # ~6% sotto RANGE_LOW
|
||||
TAKE_PROFIT = 760 # ~5,5% sopra RANGE_HIGH
|
||||
SLIPPAGE_BPS = 50 # 0,5%
|
||||
FEE_BPS = 25 # PancakeSwap v2
|
||||
```
|
||||
|
||||
Verifica break-even: passo ≈ 2,7% > `1,5 × (2×0,75%) = 2,25%` ✅
|
||||
|
||||
---
|
||||
|
||||
*Questo documento descrive la strategia. L'implementazione (ethers v6, gestione sicura
|
||||
della chiave, calcolo slippage, stato persistente, backtester) va sviluppata a parte,
|
||||
con test, e validata secondo §7 prima di qualsiasi capitale reale.*
|
||||
Reference in New Issue
Block a user