# 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`