> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/implementation-ledger/ns-367-live-book-paper-trading.md). # NS-367 · Production live-book paper trading ## Outcome NIGHTSHIFT now exposes explicit `PAPER`, `APPROVAL`, and `LIVE` authority modes on every perpetual rail without reviving the fixture-only development paper APIs. PAPER is a browser-local immediate-fill simulation over the same fresh, normalized Arcus, Hyperliquid, or Lighter L2 book already rendered by the terminal. APPROVAL preserves the reviewed no-send/human-confirmation path. LIVE remains visibly fail-closed unless the server reports that the selected venue is both mainnet and ready. ## Official evidence reviewed * Hyperliquid's official Info documentation describes `l2Book` snapshots and their bounded depth: . * Lighter's official WebSocket reference states that an order-book subscription begins with a complete snapshot, then carries state changes; `begin_nonce` must continue the previous `nonce`: . * Arcus's official L2 reference remains the adapter provenance URL: . It returned an upstream documentation error during this review, so this milestone does not infer any new Arcus semantics from unavailable prose. The existing strict Arcus REST/stream normalizer and live readiness state remain the only paper input authority. ## Implemented boundary * A fresh, two-sided, uncrossed, strictly sorted book no more than 30 seconds old is mandatory. Missing transport, sequence gaps, stale/future timestamps, malformed levels, non-canonical decimals, and crossed books block the simulation. * Market paper orders consume the currently visible opposite-side levels only. Crossing paper limits consume only levels at or better than the exact limit. Unsupported remainder is `partial` or `unfilled`; it never becomes a resting order or future fill. * Provider numbers are converted to bounded canonical decimal strings before BigInt arithmetic. Filled quantity, remainder, per-level and aggregate notional, weighted price, position average, realized PnL, and current-market live-book-mid PnL remain deterministic. Non-terminating averages are explicitly marked rounded half-up to 12 decimal places. * The ledger is strict schema v1, maximum 64 KiB, 100 executions, and 50 venue-symbol positions. Unknown fields, duplicate intent IDs, invalid arithmetic, malformed state, and oversized payloads lock the surface rather than being coerced. * A user must choose the browser-local starting capital; no default or fabricated balance exists. The ledger stores no account, wallet, key, token, endpoint, or signer data and is excluded from server backup/telemetry authority. * Paper executions are idempotent by intent ID. A two-step in-panel reset removes only the local paper ledger. * Fees, funding, liquidation, margin, resting orders, queue priority, future fills, and venue acknowledgements are deliberately not modeled. Every result declares `executionCapability: "none"` and is labelled paper evidence, never a venue order or fill. * The production `404 NOT_FOUND` boundary for `/api/rhc/paper/replay`, `/api/nightshift/agents/replay`, `/api/nightshift/league`, and `/api/nightshift/strategies/compile` is unchanged. ## Failure and UI coverage * Deterministic tests cover exponent expansion, multi-level weighted fills, partial depth, non-crossing limits, stale/future/unready/crossed/unsorted books, exact input rejection, idempotency, position averaging/close/cross, realized/unrealized PnL, strict storage parsing, tamper rejection, and mode fallback. * Production browser QA exercised a real fresh Hyperliquid paper fill, reload persistence, Arcus and Lighter actionable books, the server-owned LIVE lock, two-step reset, APPROVAL restoration, and a 390 × 844 responsive viewport with no horizontal overflow. * A clean production reload produced no new console warnings or errors. The temporary QA ledger was removed and APPROVAL mode restored. ## Validation ``` pnpm --filter @terminal/web test -- --run app/terminal/live-book-paper.test.ts pnpm --filter @terminal/web exec tsc --noEmit pnpm --filter @terminal/web build pnpm local:restart pnpm local:health ``` Final `pnpm handoff:verify` passed: repository typecheck, 83 web test files / 502 tests, 64 local operations tests, 71 Python tests, Python lint, real signer recovery, signer-store backup integration, production build, live-provider smoke coverage, fixture-route `404` assertions, CSP/security checks, secret scan, and handoff integrity. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://nytshift.gitbook.io/nytshift-docs/implementation-ledger/ns-367-live-book-paper-trading.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.