okx-codex-trader/docs/superpowers/specs/2026-04-16-okx-local-paper-engine-design.md

OKX Local Paper Engine Design

Goal

Keep OKX as a market data source only, and move simulated trading fully local.

The revised project must:

• fetch public OKX market candles
• backtest locally on historical candles
• ask local Codex CLI for a validated signal
• simulate order execution, positions, and equity locally without calling OKX trading endpoints

Non-Goals

This revision does not include:

• OKX demo order placement
• OKX account reads for positions or balances
• live trading
• spot support
• order book simulation
• partial fills
• fee modeling
• slippage modeling

Runtime Contract

• fetch-history uses public OKX market data and must not require API credentials
• backtest uses public OKX market data and must not require API credentials
• analyze uses public OKX market data and local codex
• paper-order uses local state only
• positions uses local state only

Local State

The local paper engine stores one JSON file at:

• /home/lxy/okx-codex-trader/paper_state.json

The file contains:

• cash balance in USDT
• open positions keyed by symbol and side
• realized pnl
• last updated timestamp

Initial state rules:

• if the file does not exist, paper-order and positions initialize it implicitly
• initial cash balance is 10_000 USDT
• initial positions are empty
• realized pnl starts at 0

Commands

fetch-history

Unchanged behavior:

• fetch public OKX candles for BTC-USDT-SWAP or ETH-USDT-SWAP
• print normalized candles

backtest

Unchanged behavior:

• fetch public OKX candles
• run local 10/20 SMA backtest

analyze

Unchanged behavior:

• fetch public OKX candles
• call local codex
• validate JSON signal

paper-order

Changed behavior:

• read validated signal from --signal-file
• never call OKX trading endpoints
• update paper_state.json

Rules:

• action = flat
  • no order sent
  • no position change
  • return noop result
• action = long
  • open or add to long position for symbol
• action = short
  • open or add to short position for symbol
• order price basis:
  • entry_price if provided
  • otherwise latest OKX public market price
• margin used:
  • explicit --margin-usdt
• notional:
  • margin_usdt * leverage
• position quantity:
  • notional / price
• required cash:
  • exactly margin_usdt
• if cash balance is smaller than margin_usdt, fail

State updates:

• reduce cash by margin_usdt
• add position quantity to matching symbol/side bucket
• recompute average entry price for that bucket

This v1 paper engine does not:

• net long and short
• auto-close opposite positions
• reserve maintenance margin
• apply fees or slippage
• apply TP/SL automatically

positions

Changed behavior:

• read local paper_state.json
• print current local positions only

Data Model

Add local paper engine models:

• PaperPosition
  • symbol
  • side
  • quantity
  • avg_entry_price
  • margin_used
• PaperState
  • cash_usdt
  • realized_pnl
  • positions
  • updated_at

Error Handling

Allowed failures:

• invalid signal file
• insufficient local cash
• invalid local state file shape
• public OKX market data failure
• missing codex executable for analyze

No fallback logic.

Testing

Add tests for:

• public candle fetch works without credentials
• paper-order initializes missing paper_state.json
• paper-order uses explicit entry_price when present
• paper-order uses latest public market price when entry_price = null
• paper-order reduces cash by exact margin_usdt
• paper-order increases matching local position
• paper-order recomputes average entry price when adding to same side
• paper-order rejects when local cash is insufficient
• positions reads local state instead of OKX account positions