# okx-codex-trader

Minimal project skeleton for an OKX public-data and local paper-trading CLI.

## CLI usage

```bash
python -m okx_codex_trader.cli fetch-history --symbol BTC-USDT-SWAP --bar 1H --limit 50
python -m okx_codex_trader.cli backtest --symbol BTC-USDT-SWAP --bar 1H --limit 200 --leverage 2
python -m okx_codex_trader.cli analyze --symbol BTC-USDT-SWAP --bar 1H --limit 50 --output-file signal.json
python -m okx_codex_trader.cli backtest-report --symbol BTC-USDT-SWAP --bar 1H --limit 500 --leverage 2 --output-file backtest-report.html
python -m okx_codex_trader.cli backtest-bbmr-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --output-file bbmr-sampled-report.html
python -m okx_codex_trader.cli backtest-bbsb-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --output-file bbsb-sampled-report.html
python -m okx_codex_trader.cli backtest-donchian-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --entry-window 20 --exit-window 10 --stop-loss-pct 0.01 --output-file donchian-sampled-report.html
python -m okx_codex_trader.cli backtest-rsi2-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --trend-sma 50 --rsi-length 2 --rsi-long-threshold 10 --rsi-short-threshold 90 --exit-rsi 50 --output-file rsi2-sampled-report.html
python -m okx_codex_trader.cli backtest-ema-pullback-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --fast-ema 20 --slow-ema 50 --stop-buffer-pct 0.005 --output-file ema-pullback-sampled-report.html
python -m okx_codex_trader.cli paper-order --symbol BTC-USDT-SWAP --signal-file signal.json --margin-usdt 100
python -m okx_codex_trader.cli positions --symbol BTC-USDT-SWAP
OKX_TRADING_ENV=live python -m okx_codex_trader.cli okx-account --symbol BTC-USDT-SWAP --currency USDT
OKX_TRADING_ENV=live python -m okx_codex_trader.cli okx-order --symbol BTC-USDT-SWAP --signal-file signal.json --margin-usdt 5 --max-margin-usdt 5 --confirm-live
```

Supported symbols are `BTC-USDT-SWAP` and `ETH-USDT-SWAP`. Backtest leverage is restricted to `1`, `2`, or `3`.

Sampled reports generate one self-contained HTML file with switchable sampled windows, trade journals, price/equity charts, and aggregate metrics.

`fetch-history`, `backtest`, and `paper-order` use public OKX market data only. `paper-order` and `positions` persist local simulated state in `paper_state.json`.

Authenticated OKX commands require `OKX_API_KEY`, `OKX_API_SECRET`, `OKX_API_PASSPHRASE`, and `OKX_TRADING_ENV=demo|live`. Live orders require `--confirm-live`; every OKX order command also requires `--max-margin-usdt`, and rejects larger `--margin-usdt`.

## Verification notes

- Public OKX market-data calls were exercised in automated tests through the client contract and CLI flow.
- Local `codex` runtime behavior outside mocked subprocess tests still requires manual verification.