TESTNET_TRADING_PLAN.md

# Testnet Trading Implementation Plan

## Goal
Mirror the DRL bot's LONG/SHORT trading decisions to Binance Testnet with real order execution and full dashboard visibility.

## Architecture

### Constraints
- Binance Testnet (testnet.binance.vision) is **SPOT only** — no futures/perpetuals
- LONG positions: execute real BUY orders on testnet
- CLOSE LONG: execute real SELL orders on testnet
- SHORT/CLOSE SHORT: recorded as conceptual trades (spot can't truly short); if base currency held, it is sold

### Components

#### 1. `src/api/testnet_executor.py` (NEW)
- `TestnetExecutor` class — singleton used by orchestrator and api_server
- `mirror_trade(bot_trade, bot_result)` — translates bot decision → real testnet order
- `get_current_positions()` — live positions with current prices + unrealized PNL
- `get_trades(limit)` — read from `logs/testnet_trades.json`
- `get_pnl_summary()` — realized + unrealized PNL, win rate
- Stores each trade in `logs/testnet_trades.json` (line-delimited JSON)
- Uses `BinanceConnector` for all API calls
- Reads `BINANCE_TESTNET_API_KEY` / `BINANCE_TESTNET_API_SECRET` from env

#### 2. `src/ui/api_server.py` (MODIFIED — 4 new endpoints)
- `GET /api/testnet/trades` — trade history from testnet_trades.json
- `GET /api/testnet/positions` — open positions with live prices + unrealized PNL
- `GET /api/testnet/pnl` — realized + unrealized PNL summary + equity curve data
- `POST /api/testnet/execute` — manually trigger a testnet trade (for testing)

#### 3. `live_trading_multi.py` (MODIFIED — auto-execution hook)
- `MultiAssetOrchestrator.__init__`: instantiate `TestnetExecutor` if `TESTNET_MIRROR=true`
- `run_single_cycle()`: after each bot decision, call `self.testnet_executor.mirror_trade()`
- Log both dry-run result and testnet execution result
- Guard with try/except so testnet failures never block the main trading loop

#### 4. `src/ui/app.py` (MODIFIED — enhanced Testnet tab)
New sections added to the Testnet tab (all data from API endpoints):
- **Open Positions table**: symbol, side, entry price, current price, unrealized PNL, SL, TP
- **Trade History table**: timestamp, symbol, action, price, amount, PNL, order_id
- **PNL Summary**: realized, unrealized, total, win rate, total trades
- **Equity Curve chart**: cumulative PNL over time (Plotly line chart)
- **Live Order Book**: open/pending orders from `/api/testnet/orders`

#### 5. `tests/test_testnet_trading.py` (NEW)
- Test testnet connectivity
- Test place a small market order on testnet
- Test `/api/testnet/trades` returns list
- Test `/api/testnet/positions` returns list
- Test PNL calculation

## Data Flow

```
Bot run_iteration()
    └─> execute_trade() → trade dict
                └─> [if TESTNET_MIRROR=true]
                        └─> TestnetExecutor.mirror_trade()
                                ├─> BinanceConnector.place_market_order()  (50%)
                                ├─> BinanceConnector.place_limit_order()   (50%)
                                └─> _save_trade() → logs/testnet_trades.json

Dashboard (app.py Testnet Tab)
    ├─> GET /api/testnet/status    (existing — balance/portfolio)
    ├─> GET /api/testnet/positions (new — open bot-mirrored positions)
    ├─> GET /api/testnet/trades    (new — trade history)
    ├─> GET /api/testnet/pnl       (new — PNL + equity curve)
    └─> GET /api/testnet/orders    (existing — open orders)
```

## Trade Record Schema
```json
{
  "symbol": "BTCUSDT",
  "ccxt_symbol": "BTC/USDT",
  "action": "OPEN_LONG_SPLIT",
  "side": "BUY",
  "price": 43250.50,
  "filled_price": 43251.00,
  "amount": 0.00578,
  "sl": 41087.98,
  "tp": 46000.25,
  "confidence": 0.72,
  "timestamp": "2026-03-19T14:32:00.000Z",
  "order_id": "12345678",
  "limit_order_id": "12345679",
  "limit_price": 43034.87,
  "limit_amount": 0.00579,
  "executed": true,
  "error": null,
  "pnl": null,
  "dry_run": false
}
```

## Environment Variables
- `TESTNET_MIRROR=true` — enables auto-execution hook (default: false)
- `BINANCE_TESTNET_API_KEY` — testnet API key (already set)
- `BINANCE_TESTNET_API_SECRET` — testnet API secret (already set)
- `BINANCE_TESTNET_PROXY_URL` — optional Cloudflare proxy (already set)

## Risk Controls
- TestnetExecutor failures are caught and logged — never block main loop
- Minimum trade value: $10 USDT
- Max position: 25% of testnet USDT balance × confidence scale
- Split entry: 50% market + 50% limit (mirrors bot logic)
- No automatic SL/TP orders placed (bot logic manages exits and mirrors them)