# Binance Live Mode Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add an explicit Binance Spot production mode without weakening the existing dry-run and Spot Testnet safeguards.

**Architecture:** Keep environment selection in `TradingMode` and `Settings`. Validate REST and WebSocket hosts based on the selected mode, then let execution and runner code treat `testnet_live` and `live` as real order-submission modes.

**Tech Stack:** Python 3.12, Pydantic Settings, Typer CLI, pytest, httpx.

---

### Task 1: Add Production Mode Configuration

**Files:**
- Modify: `src/binance_quant/models.py`
- Modify: `src/binance_quant/config.py`
- Test: `tests/test_config.py`

- [x] **Step 1: Write failing configuration tests**

Add tests that expect `TradingMode.LIVE`, production URL acceptance in `live`, testnet URL rejection in `live`, and credential requirements for both `testnet_live` and `live`.

- [x] **Step 2: Run tests to verify failure**

Run: `pytest tests/test_config.py tests/test_execution.py tests/test_runner.py -q`

Expected: FAIL because `TradingMode.LIVE` does not exist and URL validation only allows Testnet.

- [x] **Step 3: Implement production mode settings**

Add `LIVE = "live"` to `TradingMode`. Replace field-level URL validators with a model-level validator that checks REST and stream hosts against `testnet_live` or `live`.

- [x] **Step 4: Verify configuration tests pass**

Run: `pytest tests/test_config.py -q`

Expected: PASS.

### Task 2: Route Live Mode Through Real Execution

**Files:**
- Modify: `src/binance_quant/execution.py`
- Modify: `src/binance_quant/runner.py`
- Test: `tests/test_execution.py`
- Test: `tests/test_runner.py`

- [x] **Step 1: Write failing execution tests**

Add tests that expect `TradingMode.LIVE` to call `exchange.create_market_order()` and `exchange.account()`.

- [x] **Step 2: Run tests to verify failure**

Run: `pytest tests/test_config.py tests/test_execution.py tests/test_runner.py -q`

Expected: FAIL because `TradingMode.LIVE` does not exist.

- [x] **Step 3: Implement live execution routing**

Update `ExecutionEngine.execute()` and `_account_for_mode()` to treat `TradingMode.LIVE` the same as `TradingMode.TESTNET_LIVE`.

- [x] **Step 4: Verify execution tests pass**

Run: `pytest tests/test_execution.py tests/test_runner.py -q`

Expected: PASS.

### Task 3: Update Examples, Script Text, And Documentation

**Files:**
- Modify: `.env.example`
- Modify: `README.md`
- Modify: `scripts/run.ps1`
- Modify: `tests/test_run_script.py`

- [x] **Step 1: Update docs and examples**

Document `BINANCE_MODE=live`, production REST/WebSocket URLs, and the fact that `trade-loop` remains dry-run only while the CLI `trade` command can use configured modes.

- [x] **Step 2: Update script terminology**

Keep script safety defaults. Update quote and error messages so the read path uses the configured REST base URL instead of hardcoded Testnet language.

- [x] **Step 3: Verify script and README tests**

Run: `pytest tests/test_run_script.py -q`

Expected: PASS.

### Task 4: Full Verification

**Files:**
- All modified files

- [x] **Step 1: Run full test suite**

Run: `pytest -q`

Expected: PASS.

- [x] **Step 2: Review diff**

Run: `git diff -- src tests README.md .env.example scripts/run.ps1 docs/superpowers/plans/2026-06-20-binance-live-mode.md`

Expected: Diff only includes live-mode support, examples, docs, and tests.