# okx-codex-trader

Research and live-observation workspace for OKX crypto futures strategies.

The project started as a small OKX CLI and now contains:

- local OKX candle cache and data validation tools
- strategy research and backtest scripts
- generated research reports
- a live ETH BB squeeze executor with strict risk caps
- multiple read-only observer services for candidate strategies

Live trading exists in this project. Treat order-submission paths as production code.

## Start Here

Read these files in order when opening a new session:

1. `AGENTS.md` - repo-specific agent rules.
2. `docs/current-status.md` - current live strategy, observers, recent findings, and next work.
3. `docs/operations.md` - server, systemd services, monitoring, deployment, and safety commands.
4. `docs/architecture.md` - package/script/report boundaries and current modularization state.
5. `docs/documentation-guide.md` - where to put durable docs vs generated research reports.

Current server:

- SSH: `ubuntu@66.253.42.170`
- App dir: `/opt/okx-codex-trader`
- Env file: `/etc/okx-codex-trader/okx.env`
- Main live service: `bb-squeeze-executor.service`

## Repository Layout

- `okx_codex_trader/` - reusable package code: OKX client, candle models, live execution planning, strategy helpers, reporting primitives.
- `scripts/` - research searches, signal-intent builders, observers, and live runners.
- `reports/` - generated research outputs and latest operational snapshots.
- `docs/` - durable human-maintained project documentation.
- `deploy/` - systemd unit files and install helpers.
- `tests/` - unit and regression tests.
- `data/okx-candles/` - local candle cache, not a source module.
- `var/` - runtime state and event logs, not source.

## Local Commands

Use `rtk` for shell commands in this repo.

```bash
rtk .venv/bin/python -m pytest -q
rtk .venv/bin/python scripts/summarize_readonly_observers.py
rtk .venv/bin/python scripts/build_high_frequency_portfolio_observation_intent.py
```

Older CLI commands are still available:

```bash
rtk .venv/bin/python -m okx_codex_trader.cli fetch-history --symbol BTC-USDT-SWAP --bar 1H --limit 50
rtk .venv/bin/python -m okx_codex_trader.cli okx-account --symbol ETH-USDT-SWAP --currency USDT
```

Authenticated OKX commands require `OKX_API_KEY`, `OKX_API_SECRET`, `OKX_API_PASSPHRASE`, and `OKX_TRADING_ENV=demo|live`.

## Live Safety

- Do not place live orders unless explicitly asked.
- The deployed live path is intentionally small risk.
- Read-only observers must keep `submitted_orders: 0` and must not call OKX order APIs.
- Any strategy promotion requires a fresh read-only observation period and backtest review.

## Latest Operational Snapshot

The latest observer snapshot is generated by:

```bash
rtk .venv/bin/python scripts/summarize_readonly_observers.py
```

Current checked-in snapshot:

- `reports/live-recent/readonly-observers-snapshot.md`