okx-codex-trader/reports/eth-exploration/okx-order-support-plan.md

OKX order support minimum implementation plan

Static implementation plan only. No OKX request, order, or cancel was made.

Goal

ETH-focused quasi-live portfolio needs a full order lifecycle before any submit-capable runner is valid.

Minimum direct path: first add read-only payload/state/reconciliation support, then add submit-capable order and cancel calls behind explicit commands.

Current code facts

okx_codex_trader/okx_client.py

• Signed _request already supports GET/POST with params/json_body.
• place_order is a single-order submitter.
• place_order emits ordType=market or ordType=limit only.
• No batch-orders, orders-pending, cancel-order, order status, or fills method exists.
• get_positions reads exchange positions but is not tied to portfolio-owned state.

tests/test_okx_client.py

• DummySession records request path/body and can support endpoint-level client tests.
• Existing tests cover request signing, live/demo header, contract sizing, leverage validation, single order payload, and position parsing.
• No tests cover post_only payloads, batch payloads, order list/cancel/status/fills, or state persistence.

okx_codex_trader/cli.py

• okx-account is read-only and returns balance plus positions.
• okx-order is submit-capable and calls place_order.
• No read-only ETH order-intent/state command exists.
• No quasi-live state path or append-only lifecycle log is wired.

Required OKX API surface

Capability	Endpoint	Boundary
single post-only limit order payload	POST /api/v5/trade/order	submit-capable only after read-only payload rendering is tested
batch entry orders	POST /api/v5/trade/batch-orders	submit-capable; read-only stage renders the exact array only
list open orders	GET /api/v5/trade/orders-pending	read-only
cancel open order	POST /api/v5/trade/cancel-order	submit-capable; read-only stage renders cancel intents only
cancel open orders in batch	POST /api/v5/trade/cancel-batch-orders	submit-capable; read-only stage renders cancel intent array only
order status	GET /api/v5/trade/order	read-only
recent fills	GET /api/v5/trade/fills	read-only

State persistence is local state, not an OKX API call. Minimum file: state/eth_robust_twap_15m_live.json.

Read-only boundary

• Render post_only single and batch order payloads without calling POST /api/v5/trade/order or /batch-orders.
• Read account balance, positions, pending orders, order details, and fills.
• Write local state snapshots and append-only JSONL audit events.
• Render cancel intents without calling cancel endpoints.

Submit-capable boundary

• POST /api/v5/trade/order with ordType=post_only.
• POST /api/v5/trade/batch-orders.
• POST /api/v5/trade/cancel-order.
• POST /api/v5/trade/cancel-batch-orders.
• Any reduce-only market close path.

Minimum patch plan by file

okx_codex_trader/okx_client.py

• Add small dataclasses or typed dicts only if needed by return values: OkxOrder, OkxFill, OkxOrderAck.
• Add render_post_only_limit_order_payload(...) as a non-submitting function using existing _format_number and build_contract_size.
• Add render_eth_entry_batch_payloads(...) that returns exactly three post_only payloads for offsets 0.003, 0.006, 0.009.
• Add list_open_orders(symbol) calling GET /api/v5/trade/orders-pending with instType=SWAP and instId=symbol.
• Add get_order(symbol, ord_id=None, client_order_id=None) calling GET /api/v5/trade/order.
• Add list_fills(symbol) calling GET /api/v5/trade/fills with instType=SWAP and instId=symbol.
• Add cancel_order(symbol, ord_id=None, client_order_id=None) and cancel_batch_orders(symbol, order_ids) only when moving past read-only intent.
• Do not change existing place_order semantics for the first patch; it is not suitable for the ETH portfolio lifecycle.

okx_codex_trader/cli.py

• Add read-only eth-robust-twap-order-intent command that prints signal, three entry payloads, expiry, and state transition preview.
• Add read-only eth-robust-twap-open-orders command that lists current OKX pending orders for ETH-USDT-SWAP.
• Add read-only eth-robust-twap-reconcile command that reads state, queries open orders/status/fills, and writes a new local state snapshot plus JSONL audit event.
• Keep okx-order unchanged and do not route portfolio intents through it.
• Only after read-only commands pass tests, add explicit submit commands for batch entry and cancellation.

tests/test_okx_client.py

• Add tests for post_only payload shape: ETH-USDT-SWAP, isolated, buy, long, post_only, px, sz, deterministic clOrdId.
• Add tests for batch payload shape: exactly three orders, offsets 0.003/0.006/0.009, each level sized independently and rounded to lotSz.
• Add tests for GET /api/v5/trade/orders-pending params and normalized open-order state values.
• Add tests for POST /api/v5/trade/cancel-order and /cancel-batch-orders request bodies before enabling submit commands.
• Add tests for GET /api/v5/trade/order by ordId and by clOrdId.
• Add tests for GET /api/v5/trade/fills parsing fillSz, fillPx, tradeId, ordId, clOrdId, fee, and fillTime.
• Add tests that malformed OKX lifecycle payloads raise the existing stable invalid-payload error.

new okx_codex_trader/eth_robust_twap_state.py

• Add only the dedicated state schema and load/save functions needed by the ETH quasi-live lifecycle.
• Persist exchange order ids, client order ids, fills, position, last confirmed candle, active state, and audit cursor.
• Reject state whose symbol/bar/strategy_id does not match the command arguments.

new tests/test_eth_robust_twap_state.py

• Add load empty state test.
• Add save/read roundtrip for one signal with three open orders and one partial fill.
• Add state mismatch rejection tests for symbol, bar, and strategy_id.

Test checklist

• Existing tests: rtk .venv/bin/pytest tests/test_okx_client.py
• New client tests for render-only post_only payloads make no DummySession requests.
• New client tests for list_open_orders/get_order/list_fills assert method/path/params and parsed output.
• New cancel tests assert request body shape but stay behind commands that are not wired in the read-only phase.
• New CLI tests assert read-only order-intent/reconcile commands do not call submit/cancel endpoints.
• New state tests assert deterministic state roundtrip and event append order.

Sources

• OKX API v5 docs: https://www.okx.com/docs-v5/en/
• Live readiness report: reports/eth-exploration/eth-focused-portfolio-live-readiness.md
• ETH live execution plan: reports/eth-exploration/eth-robust-twap-live-plan.md