# Hyperliquid paper runtime: API-degraded fail-closed pattern

Use this reference when a paper/live-preview learning harness reads real Hyperliquid market data but must never place live orders. The durable lesson is the **fail-closed degraded-mode pattern**, not any one transient network error.

## Trigger

A paper/runtime loop depends on exchange `/info` market-data calls and can encounter DNS/network/API degraded states such as connection errors, timeouts, route failures, or structured exchange errors.

## Required behavior

- Catch market-data exceptions at the runtime iteration boundary, not inside strategy logic.
- Return/report an explicit `status="degraded"` or equivalent for the iteration.
- Do **not** create new entries, fills, order intents, or exchange-signed actions while degraded.
- Keep strategy and risk functions pure; the strategy should not call the exchange directly.
- Journal runtime health so monitors can distinguish API outage from strategy silence.
- For each candidate signal that cannot be evaluated safely, journal a blocked shadow signal with enough structure for dashboards/scorecards:
  - `block_reason` includes `api_degraded`
  - `final_decision` like `blocked:api_degraded`
  - `data_quality_allowed=false`
  - depth/market-quality booleans false or unavailable
  - risk gate result `allowed=false` with reason `api_degraded`
- Preserve paper-only/mainnet-read-only boundaries: Mainnet market data may be read-only; order execution remains local `PaperExecutor` unless an explicitly approved Testnet tool is running.

## Verification checklist

- Unit test forces the market-data client to raise a network/API exception and asserts:
  - iteration returns degraded instead of raising
  - no executor/order method is called
  - health journal entry is written
  - blocked shadow signals are journaled for the configured coins
- Run focused tests for the runtime and replay/scorecard path.
- Run full test suite plus `compileall` before committing.
- If processes are restarted, verify actual process identity and environment flags (`CTB_PAPER_TRADING=true`, `CTB_DRY_RUN=false`, expected strategy/runtime dir) before reporting them healthy.

## Reporting language

When this happens, report it as an API/connectivity degraded event with fail-closed behavior. Do not call it a strategy failure, do not weaken live gates, and do not infer profitability or lack of signals from the outage window.