> 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/engineering-guide/05-paper-trading.md). # Paper trading [← Market data](/nytshift-docs/engineering-guide/04-market-data-and-charting.md) · [Documentation home](/nytshift-docs/start-here/readme.md) · Next: [Bring Your Own Agent →](/nytshift-docs/engineering-guide/06-bring-your-own-agent.md) NYTSHIFT PAPER is a deterministic simulation boundary that consumes real, fresh, normalized books without acquiring venue authority. It is designed to test policy and workflow, not to cosmetically imitate an exchange account. In the AgentOps model, PAPER is the first qualification environment. It can expose strategy behaviour and policy violations without granting a venue-order capability. Human and agent PAPER still use separate evidence stores; the unified `PaperRun` and Flight Recorder are next product layers. ![Browser-local PAPER mode using a live book, user-defined capital and deterministic replay without creating a venue order](https://365345826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD02RJbcs8ypn0hikgNUk%2Fuploads%2Fgit-blob-ed4913ea079aa10bb00c8bf014b565e04547e70d%2F04-live-book-paper.png?alt=media) ## Two paper surfaces | Surface | Ownership | Lifetime | Intended use | | -------------- | ----------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- | | Terminal PAPER | Browser-local versioned ledger | Browser storage; monitoring only while the tab is open | Manual live-book simulation, local GTC/protection and portfolio inspection | | MCP `paper.v1` | Private server store owned by one expiring connection | Bounded by connection/policy retention | Customer-owned agent rehearsal under immutable server policy | Both surfaces have `executionCapability: none`. Neither can be promoted into a venue order or used as signer input. ## Agent PAPER scope Agent `paper.v1` accepts immediate market or limit simulation requests against a fresh exact book. The platform-operator-issued policy fixes venue and symbol scope, starting capital, order frequency, spread, slippage, market and portfolio notional, daily loss and drawdown limits. The connection-owned ledger retains executions, positions and risk-lock state. Agent PAPER has no local GTC book, protection plans, chart controls, leverage profile, margin model or liquidation estimate. Its execution record explicitly labels fees, funding and liquidation as not modeled. The advanced GTC, position, margin, chart and protection sections below describe **Terminal PAPER** unless a section explicitly says otherwise. ## Shared immediate PAPER fill pipeline ```mermaid flowchart LR I[User/agent paper intent] --> B[Fresh exact two-sided book] B --> S[Spread gate] S --> D[Visible-depth walk] D --> L[Slippage gate] L --> N[Market and portfolio notional gates] N --> R[Loss/drawdown checkpoint] R --> F[Exact ledger fill] F --> P[Positions + realized state] ``` Every gate uses exact decimal arithmetic and conservative rounding. A rejected entry does not mutate the ledger. ## What Terminal PAPER models * exact venue/symbol identity; * live actionable bid/ask depth; * market and crossing IOC depth consumption; * local non-crossing GTC placement and deterministic later fill; * reduce-only size and direction constraints; * average entry, realized P\&L and exact remaining position; * account-wide starting capital envelope; * immutable loss, drawdown, spread, slippage and notional limits; * exact-context mark-to-market evidence; * local stop/take-profit protection from fresh same-market evidence; * a dedicated PAPER account surface for positions, open local GTC orders, fills and account evidence; * venue-rule leverage profiles with cross/isolated selection, initial and maintenance margin, estimated liquidation and live-rate funding projection; * exact partial and full reduce-only closes; * explicit-confirmation chart dragging for armed stop-loss and take-profit levels. ## What Terminal PAPER explicitly withholds * queue priority; * venue matching-engine latency; * venue fees or rebates; * funding accrual or settlement beyond the displayed current-rate projection; * venue-exact bankruptcy, liquidator-fee and auto-deleveraging effects; * partial hidden liquidity; * background execution while the browser is closed; * guaranteed protection fills; * venue order or conditional-order persistence. The UI names these omissions. Paper equity is not venue equity, available collateral or withdrawable capital. ## Position, margin and chart controls The lower account panel switches authority with the trading mode. In PAPER it reads only the strict PAPER ledger, not a disconnected live-account snapshot. Position rows expose fresh mark P\&L, entry, mark, estimated liquidation, initial and maintenance margin, margin mode, leverage and exact partial or full close actions. Order and history views expose local GTC lifecycle and simulated fills. Each open position binds a strict risk profile to its venue, symbol, leverage, margin mode and reviewed market rule. Missing or invalid rule evidence withholds liquidation rather than inventing a number. Cross and isolated liquidation values remain labelled PAPER estimates and exclude venue liquidation fees, auto-deleveraging, hidden collateral and future funding. Armed stop-loss and take-profit levels can be previewed by dragging on the chart. A separate confirmation writes the local protection plan. The open terminal performs trigger monitoring, so closing the browser removes monitoring availability. ## Immutable risk checkpoint Every PAPER ledger binds one immutable risk policy. A human defines Terminal PAPER policy at initialization; a NYTSHIFT platform operator defines agent PAPER policy when issuing the connection. Changing the policy requires a Terminal PAPER reset or a new platform-operator-issued MCP connection so earlier outcomes cannot be reinterpreted under more permissive limits. | Control | Rule | | -------------------------- | -------------------------------------------------------------------------- | | Starting capital | Exact positive USD; establishes the one-times open-entry-notional envelope | | Maximum UTC daily loss | Advances only from complete fresh marked equity | | Maximum peak drawdown | Conservatively rounded basis points from complete fresh marked equity | | Maximum entry slippage | Whole-number 1–500 bps against the first executable level | | Maximum top-of-book spread | Whole-number 1–500 bps using `(ask-bid)*20000/(ask+bid)` | | Per-market entry notional | Exact positive USD and no greater than portfolio cap | | Portfolio entry notional | Exact positive USD and no greater than starting capital | A breach pauses new standard entry and retains existing GTC rows. Reduce-only exits and local protection remain available so an entry control cannot trap simulated risk. ## Local GTC semantics The schema-v1 local book retains at most eight non-crossing orders. Placement reserves exact remaining quantity × limit price across market and portfolio caps. Orders are oldest-first and can fill at most once per newer book observation. Partial fills require another newer observation before continuing. Cross-market monitoring is intentionally venue-specific: * Hyperliquid and Arcus may use exact-context pooled streams plus REST repair. * Lighter away-market orders remain REST-only without a verified numeric market ID. * One degraded market pauses its own context without hiding unrelated orders. * Cancellation is local and idempotent; it does not send a venue cancel. ## Protection semantics The protection book retains at most eight exact venue/symbol plans. A trigger is evaluated against a fresh venue mark and can simulate a reduce-only exit only from book evidence observed at or after the trigger. Partial depth leaves exact remaining position/protection. Position drift disarms only the affected plan. Completed protection executions retain their trigger identity in the PAPER tape as `STOP LOSS` or `TAKE PROFIT`. Older ledgers created before trigger-specific identity was introduced remain readable and display the conservative legacy label `AUTO PROTECTION`. ```mermaid stateDiagram-v2 [*] --> Armed Armed --> Waiting: mark has not reached trigger Waiting --> Triggered: fresh exact mark reaches stop/take-profit Triggered --> Partial: bounded book depth Triggered --> Filled: sufficient book depth Partial --> Waiting: remainder retained Armed --> Disarmed: position/context drift Waiting --> Paused: stale or missing evidence Paused --> Waiting: fresh exact evidence returns Filled --> [*] Disarmed --> [*] ``` ## Exact portfolio marking Each open position may receive a reviewed exact venue mark. Row unrealized P\&L is unavailable when that mark is stale, absent or mismatched. Total mark-to-market paper equity is shown only when **every** open position has fresh evidence; the system never publishes a partial aggregate as complete. Implementation history: [NS-367](/nytshift-docs/implementation-ledger/ns-367-live-book-paper-trading.md) through [NS-420](/nytshift-docs/implementation-ledger/ns-420-paper-notional-limits.md), plus the [BYOA runbook](/nytshift-docs/agents-identity-and-data/bring-your-own-agent.md) for server-owned agent paper. Operational verification: [PAPER trading readiness validation](/nytshift-docs/release-and-readiness/paper-trading-readiness-validation.md). --- # 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/engineering-guide/05-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.