Add PAPER trading mode + fix partial-fill close orphaning positions

[Freecey]

Summary

Three changes in three commits (happy to split into separate PRs if you prefer):

1. feat(paper): PAPER mode — simulated fills against live market prices

There is currently no step between OFF (observe only) and LIVE (real money). This adds "mode": "PAPER": the full pipeline (scan → TA filter → AI research → risk gates → DSL exits) runs unchanged against live market data, but every authenticated exchange call routes to a simulated book (client/paper_engine.py):

• fills at the live L2 touch ± paper_slippage_bps, taker fees at paper_fee_bps
• position netting with realized PnL, reduce-only clamped to live size (never flips), pre-trade margin check
• virtual SL/TP triggers evaluated against live mids on every account-state read
• state persisted atomically to .paper-state.json (survives daemon restarts, same pattern as .dsl-state.json)
• fetch_account_state returns the virtual book in HL's exact clearinghouseState shape, so the gates, DSL engine, dashboard and status.py work without modification
• works with no HYPERLIQUID_* env vars — useful for new users evaluating a config before funding a wallet

Known approximations are documented in the module docstring and README: orders always fill in full (no book-depth exhaustion) and triggers fill at their trigger price (real markets gap) — so paper results are slightly optimistic by construction.

2. fix(exits): partial-fill close could orphan a position with no stop

The important one. In close_position_market, the DSL tracker was deregistered as soon as the reduce-only IOC returned ok=True, without checking totalSz against the requested size. On a thin book, a partial fill left the residual position live on the exchange with no stop, no floor, no timeout — exactly the failure mode this engine exists to prevent.

Now: totalSz is reconciled against the requested size, the residual is retried up to 3× (fresh size and price each pass), and if any size still remains the tracker is kept and the call returns ok=False with partial/remaining_sz details so the next DSL tick re-fires the close. Realized PnL uses the size-weighted fill price across all fills.

Also in this commit:

• rehydrate_from_exchange stamped synthesized trackers with entry_time=now, re-arming hard_timeout_minutes from scratch on every restart (a 2h50m-old position got a fresh 3h lease). It now looks up the real open time from the account's fill history (most recent open-from-flat fill), falling back to now when unavailable.
• backup SL/TP placement is retried once (the typical failure is a transient meta-cache/429 flake), and a persistent SL failure emits an error event to the session feed instead of only a log line — the position is otherwise running with the 60s DSL loop as its only stop and nobody knows.
• gate inputs: open-position notional now uses HL's positionValue (live mark) instead of |szi| × the stale analysis entry price.
• place_hl_trigger_order callers pass is_long_position= as an explicit keyword — the positional is_buy only worked because entry direction happens to equal position side.

3. fix(security): bind the API server to localhost by default

The FastAPI server (whose operator endpoints place/close real trades behind a single static token) listened on 0.0.0.0 unconditionally. Default is now 127.0.0.1, overridable via HERMES_HOST; the Dockerfile, fly.toml and the k8s configmap set HERMES_HOST=0.0.0.0 so containerized deploys behave exactly as before.

Testing

• 193 offline tests pass: the 173 existing ones (no regressions) + tests/test_paper.py (14 tests: fills, netting, reduce-only clamp, margin check, trigger firing, persistence, exchange-layer routing) + tests/test_close_and_rehydrate_fixes.py (6 regression tests: partial close keeps the tracker, residual retry, weighted fill price, dust handling, open-time from fill history, API-failure fallback).
• End-to-end PAPER smoke test against the live API with no credentials: entry filled at the real L2 touch, equity marked to live mids, virtual SL registered, clean close, state file intact.

🤖 Generated with Claude Code