# Hyperliquid v76 live-preview modularization pattern

Use when migrating the user's CryptoTradingBot from the legacy monolithic `AutoTrader.py` toward a safer Hyperliquid live-preview architecture.

## Initial repo safety

1. Start with a repo audit before edits:
   - `pwd`
   - `git remote -v`
   - `git branch --show-current`
   - `git status --short`
   - `git log --oneline -5`
   - `git diff --stat`
2. Compare with known remote refs. If GitHub is older than local paper work, do **not** reset to remote; preserve local candidate strategies, scorecard, dashboard and paper runtime code.
3. Create a feature branch such as `feature/hyperliquid-v76-live-preview`.
4. Add a repo audit document under `docs/` listing GitHub baseline, local additions, execution-relevant legacy files, and files that must not be live-enabled directly.

## Modular boundary

Create a new `src/` tree and leave legacy files intact for reference:

- `src/execution/order_intent.py`: typed `OrderIntent` dataclass. Entry intents require `stop_loss`; reduce-only exits may omit it.
- `src/strategies/...`: pure strategy functions only. They return `OrderIntent | None`; they must not import/call SDK `Exchange`, `Info`, CCXT, `market_open`, `create_order`, `fetch_positions`, or cancel calls.
- `src/execution/*executor.py`: only executor modules may send/cancel orders.
- `src/hyperliquid/rounding.py`: Hyperliquid `szDecimals`, price significant-figure rounding, min-notional validation.
- `src/risk/*`: pretrade gate, kill switch, daily loss gate, position sizer, coin-leakage gate.
- `src/reconciliation/hyperliquid_reconciler.py`: compares user state/open orders/local journal and blocks new entries if a position has no reduce-only stop.

## Hyperliquid env-specific credential loading

When working on this user's Hyperliquid execution/testnet gates, never parse a shared `.env` or fall back to global `HL_API_PRIVATE_KEY` / `HL_WALLET_ADDRESS` once env-specific files are expected.

- `env=mainnet`: load only `Mainnet.env` from `/agent/.hermes/` or `/home/agent/.hermes/`.
- `env=testnet`: load only `Testnet.env` from `/agent/.hermes/` or `/home/agent/.hermes/`.
- If the requested file is absent, or only the other network's file exists, fail closed.
- Expected file keys: `HL_WALLET_ADDRESS`, `HL_API_PRIVATE_KEY`, `API Wallet Name`, `API Key`.
- `HL_API_PRIVATE_KEY` is the API/agent-wallet private key.
- `API Key=0x...` is the API/agent-wallet public address; derive the address from `HL_API_PRIVATE_KEY` and require it to match.
- `HL_WALLET_ADDRESS` is the normal/master account address and must be passed to the Hyperliquid SDK as `account_address`.
- Never use the API-wallet public address as SDK `account_address`; block if `HL_WALLET_ADDRESS == API Key`.
- Diagnostic output may include env name, env-file path, booleans, errors, and masked addresses only; never print private keys or full secrets.
- For testnet smokes, require `will_use_mainnet_key=false` and a clean env diagnosis before placing any testnet order.

## Live-preview gates

Live execution remains blocked until both are present:

- `CTB_LIVE_TRADING_ALLOWED=true`
- exact `CTB_LIVE_CONFIRMATION` expected by the executor/preflight

Dry-run executors must return a structured plan/result and make no exchange calls.

## v76 strategy derivation

Derive `candidate_v76_hl_confirmed_squeeze_hybrid` from paper learnings:

- Primary: confirmed squeeze breakout, recent-high breakout, SMA fast >= SMA slow, volume confirmation, 5m context, breadth/relative-strength guard.
- Secondary: survival/rebound only after SMA reclaim, half risk, no blind dip-buy.
- Universe: CORE `BTC, ETH, SOL, LINK`; RESEARCH_ALT `WLD, SUI, ENA, BCH`.
- WLD remains allowed but throttled by coin-leakage gate: >50% recent top-coin share reduces risk to 0.25; >60% blocks new entries for that coin.

## TDD verification

Write RED tests before implementation for:

- `OrderIntent` validation
- Hyperliquid size/price rounding
- pretrade risk gate
- coin-leakage gate
- live executor dry-run/blocked-by-default behavior
- reconciler missing-stop detection
- v76 strategy returning intent without exchange calls

Then run focused tests, full suite, compile check, and an AST/grep scan proving strategy modules contain no exchange calls.