# REST Endpoint Selection 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:** Let Binance REST clients choose the highest-quality configured REST endpoint before making trading API calls.

**Architecture:** Add `BINANCE_REST_BASE_URLS` as a comma-separated endpoint list while keeping `BINANCE_REST_BASE_URL` backward-compatible. `BinanceSpotClient` will benchmark configured endpoints with `/v3/time` once during initialization and use the fastest successful endpoint. If all probes fail, it falls back to the first configured endpoint and preserves the normal request error path.

**Tech Stack:** Python, pydantic-settings, httpx, pytest.

---

### Task 1: Configuration

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

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

Add tests that `rest_base_urls` parses comma-separated values, defaults to all live endpoints in live mode, and rejects hosts outside the current mode.

- [ ] **Step 2: Implement config parsing**

Add `rest_base_urls`, normalize each URL with the existing HTTPS validator, and keep `rest_base_url` as the first selected URL for compatibility.

### Task 2: Client Endpoint Selection

**Files:**
- Modify: `src/binance_quant/exchange.py`
- Test: `tests/test_exchange.py`

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

Add tests that a client built with multiple base URLs probes `/v3/time`, selects the fastest successful endpoint, skips failures, and falls back to the first endpoint if all fail.

- [ ] **Step 2: Implement endpoint probing**

Add optional `base_urls`, `endpoint_probe_timeout`, and injectable `probe_clock`/`probe_client_factory` hooks for deterministic tests. Use the same proxy and `trust_env=False` behavior as trading requests.

### Task 3: Runner Wiring and Docs

**Files:**
- Modify: `src/binance_quant/ai_trader.py`
- Modify: `src/binance_quant/auto_buy.py`
- Modify: `src/binance_quant/auto_sell.py`
- Modify: `src/binance_quant/runner.py`
- Modify: `src/binance_quant/cli.py`
- Modify: `README.md`
- Test: existing runner tests

- [ ] **Step 1: Pass `settings.rest_base_urls` into every production client construction**

Keep `base_url=settings.rest_base_url` until all call sites are migrated, then pass the list where supported.

- [ ] **Step 2: Document `BINANCE_REST_BASE_URLS`**

Explain comma-separated endpoints and startup-time quality selection.

### Task 4: Verification

**Files:**
- Test: all tests

- [ ] **Step 1: Run focused tests**

Run `uv run pytest tests/test_config.py tests/test_exchange.py tests/test_auto_buy_runner.py tests/test_auto_sell_runner.py tests/test_ai_trader.py tests/test_runner.py tests/test_cli.py -q`.

- [ ] **Step 2: Run full tests**

Run `uv run pytest -q`.