# 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.*
