# HL-Bot V2 — Orderflow-First Trading Bot

Clean rewrite of the Hyperliquid BB Bot (V1) with orderflow analysis
as the primary signal source instead of LLM-dependent Bollinger Bands.

## V1 Problems (documented from live trading)

- **51% win rate** with 55 trades in 2.5 days
- **80/20 Long/Short bias** — LLM (DeepSeek V4 Flash) favors longs
- **91% rejection rate** — 560 risk rejects vs 55 submits (12-layer pipeline too strict)
- **Missing orderflow signals** — no CVD, no stacked imbalances, no volume profile
- **API spam** — 15x 429 errors from 30-second scan intervals with 4 book samples
- **Fee drag** — 4.5 bps taker x2 eats into small targets

## V2 Architecture

```
scan → orderflow snapshot → strategy scan → risk check → paper/live submit
         │                     │
         ├── L2 Book (2 samples)  ├── 8 Named Strategies (from wiki)
         ├── Recent Trades        ├── Signal alignment matrix
         ├── Candles (15m/1h/4h)  ├── Symmetric long/short
         ├── CVD Tracking         └── Deterministic (no LLM for entry)
         ├── Volume Profile
         └── Absorption Detection
```

### 8 Strategies (from ~/wiki/raw/orderflow-*.md)

1. **Absorption + Reversal** — high volume but price stalls = fake breakout
2. **Initiation + Breakout** — stacked imbalances + strong tape = real breakout
3. **Delta Divergence** — CVD diverges from price = exhaustion signal
4. **Liquidity Grab** — sweeps previous high/low then reverses = stop hunt
5. **Trend Pullback** — pullback to VWAP in confirmed trend = continuation
6. **Iceberg Follow** — large prints at single price = institutional hidden order
7. **Liquidity Vacuum** — one side of book vanishes = fast move incoming
8. **Exhaustion Fade** — RSI extreme + absorption + tape flip = reversal

### Risk Pipeline (6 layers, not 12)

1. Spread & liquidity (< 5 bps)
2. Confidence gate (> 0.55)
3. Reward:Risk ratio (> 1.5:1)
4. Noise floor (stop > 0.8x ATR)
5. Daily limits (2 losses, 6 trades)
6. Fee-adjusted edge (fees < 50% of target)

### Key Differences from V1

| Feature | V1 | V2 |
|---|---|---|
| Code | ~9,700 lines | ~4,000 lines |
| Signal source | LLM (DeepSeek) | Deterministic orderflow |
| Strategies | 6 named, LLM-validated | 8 named, no LLM needed |
| CVD tracking | Missing | Core module |
| Volume Profile | Missing | VPOC + VAH/VAL |
| Stacked imbalances | Missing | 3+ level detection |
| Long/Short bias | 80/20 | Symmetric by design |
| Risk layers | 12 (91% reject) | 6 (calibrated) |
| Scan interval | 30s | 45s |
| Book samples | 4 x 0.5s | 2 x 1.5s |
| Rate limiting | None | Token bucket (5/s) |
| Blocked coins | None | MON, PUMP, FARTCOIN |
| R:R cap | None | 4:1 max (no fantasy targets) |

## Quick Start

```bash
cd ~/hl-bot-v2
.venv/bin/python -m hlbot scan              # one-shot scan
.venv/bin/python -m hlbot paper --hours 1   # paper trading loop
.venv/bin/python -m hlbot report --hours 24 # journal summary
.venv/bin/python -m hlbot config            # show config
.venv/bin/python -m hlbot init              # create config.toml
```

## Backtest V1 Trades

```bash
.venv/bin/python scripts/backtest_v1_trades.py
```

Replays V1's actual trades through V2's strategy filter to see
which ones V2 would have rejected and the impact on PnL.

## Files

```
hlbot/
  __init__.py     — package
  models.py       — dataclasses (Candle, OrderflowSnapshot, Setup, TradePlan, etc.)
  api.py          — Hyperliquid REST client with rate limiting
  orderflow.py    — L2 book, tape, CVD, absorption, volume profile, indicators
  strategies.py   — 8 named strategy scanners
  risk.py         — 6-layer risk pipeline + position sizing
  journal.py      — JSONL append-only journal
  config.py       — TOML config loader
  cli.py          — CLI commands (scan, paper, report, config, init)
scripts/
  backtest_v1_trades.py — V1 vs V2 comparison
data/
  journal.jsonl — trade journal (paper or live)
config.toml     — configuration
```

## No Live Execution (Yet)

V2 currently only does paper trading. Live execution requires:
- Hyperliquid SDK integration (execution.py equivalent)
- Wallet private key in .env
- Position management (break-even, trailing stop)
- Explicit user approval before going live
