# Hyperliquid v76 hard gates and VM-safe verification

Use this reference when proving Hyperliquid v76 live-preview readiness for CryptoTradingBot-style systems. It captures the durable workflow lessons from hardening the v76 branch, not a one-off task log.

## Core principle

A live-preview PASS is only permission for the user to consider a separate live-preview approval. It must never place a Mainnet order automatically. Testnet proof is the technical proof path; Mainnet before explicit approval is read-only reconciliation only.

## Mainnet read-only reconciliation

- Use only the public master/subaccount address for read-only reconciliation; do **not** default to an API-agent wallet address.
- Private keys are not required for account-state reads.
- Output must mask the address and include account/equity fields without secrets:
  - `address_masked`
  - `equity`
  - `free_usdc`
  - `margin_usage_pct`
  - `positions`
  - `open_orders`
  - `stops_missing_count`
  - `block_new_entries`
  - `recommended_actions`
- Keep read-only account adapters free of `Exchange` imports. Import only Hyperliquid `Info`/info-style clients for reconciliation.
- If the public address is held in a local secret file, source it carefully in the shell and never print raw values. Print only masked addresses.

## Testnet execution gates

For testnet smokes, require at minimum:

```bash
CTB_HL_ENV=testnet
CTB_TESTNET_TRADING_ALLOWED=true
```

If the user explicitly provides these in the command, do not invent an additional confirmation gate unless the tool/contract already requires it. Live/Mainnet gates remain stricter and separate.

### ALO+Cancel proof

The ALO+Cancel smoke should:

1. Load testnet meta.
2. Resolve BTC asset metadata and `szDecimals`.
3. Fetch a mid price.
4. Place a far-from-market ALO/GTC limit order expected not to fill.
5. Read open orders for the correct testnet user address.
6. Cancel by `oid` when available, otherwise by `cloid`.
7. Read open orders again.
8. Journal `cloid`, `oid`, rounded size, rounded price, order/cancel responses, and before/after open orders.

**Pitfall:** Hyperliquid SDK responses can return HTTP-success-shaped objects with `{"status":"err", "response":"..."}`. Never treat such responses as gate success. Mark the smoke `error` and preserve the exchange message in the journal, masking any addresses in user-facing summaries.

### scheduleCancel proof

The deadman smoke should:

1. Set `scheduleCancel` on testnet.
2. Journal the response and scheduled time.
3. Clear the plan or explicitly document controlled expiry.
4. Open no positions.

Treat `schedule_cancel()` responses with `status == "err"` as `error`, not `ok`. `cancel_plan_removed` is true only if the clear response is not an exchange error.

### Fill + exchange-level stop proof

The Fill+Stop smoke should be testnet-only and must perform a full cleanup path:

1. Set isolated leverage (2x/3x).
2. Place a minimal BTC entry order.
3. Detect fill by reading user state.
4. Immediately place a reduceOnly trigger stop-loss.
5. Reconcile:
   - position exists,
   - stop exists,
   - stop is reduceOnly,
   - stop size matches position size,
   - stop direction is opposite the position.
6. Close the position with reduceOnly order.
7. Cancel remaining open orders.
8. Final reconcile expects zero position and zero unexpected orders.
9. Journal entry/stop/close cloids, rounded size/prices, reconciler result, cleanup actions, and final positions/orders.

If the testnet API wallet is not registered on Hyperliquid testnet, the exchange may respond `User or API Wallet ... does not exist`. This is not a tool failure and not a reason to weaken gates; report the testnet gate as red and ask for a dedicated registered testnet API wallet/address.

## Market context and data-quality gate

Live-preview candidates must not depend on a context universe that omits the main PnL drivers. For v76, collect at least:

- CORE: `BTC`, `ETH`, `SOL`, `LINK`
- RESEARCH_ALT: `WLD`, `SUI`, `ENA`, `BCH`
- Optional watch: `HYPE`

Per coin, persist:

- RSI
- SMA fast/slow
- ATR
- funding
- volume
- mid
- `spread_pct` from L2 book when available
- timestamp
- `reliability_score`
- `stale_data`

A `DataQualityGate` must block new entries when context is stale, L2Book is missing for the traded coin, spread is too high, API/connectivity health is degraded, or websocket/context feeds are stale. The scorecard should expose `blocked_by_data_quality_count`.

## API/connectivity health

Add explicit telemetry and gates for:

- `api_429_count`
- `no_route_count`
- `ws_reconnect_count`
- `stale_context_count`
- `degraded_mode_active`

Use bounded exponential backoff and request budgeting for info endpoints. During degraded mode, block new entries but keep exits and reconciliation prioritized.

## Nonce/API-wallet safety

Before live-preview:

- Use a dedicated API wallet per trading process.
- Persist the last nonce.
- Increment atomically and lock per signer.
- Preflight must detect multiple executors using the same signer/API wallet.
- Do not run parallel testnet/live processes with the same signer.
- Do not put the master key inside the bot process.

## VM-safe scorecard and preflight verification

Avoid unstable verification patterns:

- Do not run full dashboard snapshots just to refresh scorecards.
- Do not chain scorecard generation, greps, preflight, and exchange smokes into one terminal command.
- Do not write a report file that the dashboard is simultaneously reading.

Prefer:

```bash
.venv/bin/python paper_scorecard_report.py --max-bots 8 --output /tmp/paper_scorecard_fast.txt
```

The scorecard path should read journals only, with short timeouts and separate commands. Preflight should read an explicit/latest evidence JSON so gates that were just proven by tests/smokes are not falsely reported red.

## Preflight interpretation

A final preflight should fail closed if any of these are missing:

- tests green
- compileall green
- Mainnet read-only reconcile
- testnet ALO+Cancel
- testnet scheduleCancel
- testnet Fill+Stop
- position-without-stop impossible
- DataQualityGate
- API 429/no-route handling
- v76 net scorecard gates
- NonceManager/API-wallet isolation
- Telegram alerts tested
- secrets scan clean
- Legacy AutoTrader blocked
- live flags/confirmation for live-preview discussion

Strategic gates may remain red while testnet infrastructure gates are being proven. Never phrase a FAIL as a live recommendation.