From 852d3a82658eb33b5fa7a21697badfecd12cf129 Mon Sep 17 00:00:00 2001 From: 21in7 Date: Thu, 5 Mar 2026 23:34:01 +0900 Subject: [PATCH] feat: implement multi-symbol trading design and plan documentation - Added design document outlining the architecture for multi-symbol trading, including independent TradingBot instances and shared RiskManager. - Created implementation plan detailing tasks for configuration, risk management, and execution structure for multi-symbol support. - Updated configuration to support multiple trading symbols and correlation symbols, ensuring backward compatibility. - Introduced shared RiskManager with constraints on position limits and direction to manage global risk effectively. Co-Authored-By: Claude Opus 4.6 --- .../2026-03-05-multi-symbol-trading-design.md | 209 ++++ .../2026-03-05-multi-symbol-trading-plan.md | 920 ++++++++++++++++++ 2 files changed, 1129 insertions(+) create mode 100644 docs/plans/2026-03-05-multi-symbol-trading-design.md create mode 100644 docs/plans/2026-03-05-multi-symbol-trading-plan.md diff --git a/docs/plans/2026-03-05-multi-symbol-trading-design.md b/docs/plans/2026-03-05-multi-symbol-trading-design.md new file mode 100644 index 0000000..e121198 --- /dev/null +++ b/docs/plans/2026-03-05-multi-symbol-trading-design.md @@ -0,0 +1,209 @@ +# Multi-Symbol Trading Design + +## 개요 + +현재 XRP 단일 심볼 선물 거래 봇을 TRX, DOGE 등 다중 심볼 동시 거래로 확장한다. + +## 요구사항 + +- **거래 심볼**: XRPUSDT, TRXUSDT, DOGEUSDT (3개, 추후 확장 가능) +- **상관관계 심볼**: BTCUSDT, ETHUSDT (기존과 동일) +- **ML 모델**: 심볼별 개별 학습·배포 +- **포지션**: 심볼별 동시 포지션 허용 (최대 3개) +- **리스크**: 심볼별 독립 운영 + 글로벌 한도 (일일 손실 5%) +- **동일 방향 제한**: 같은 방향(LONG/SHORT) 최대 2개까지 (BTC 급락 시 3배 손실 방지) + +## 접근법: 심볼별 독립 TradingBot 인스턴스 + 공유 RiskManager + +기존 TradingBot의 단일 포지션 상태 머신을 유지하면서, 각 심볼마다 독립 인스턴스를 생성하고 `asyncio.gather()`로 병렬 실행한다. RiskManager만 싱글턴으로 공유하여 글로벌 리스크를 관리한다. + +### 선택 이유 + +- 기존 TradingBot 상태 머신 수정 최소화 +- 심볼 간 완전 격리 — 한 심볼의 에러가 다른 심볼에 영향 없음 +- 점진적 확장 용이 (새 심볼 = 새 인스턴스 추가) +- 각 단계마다 기존 XRP 단일 모드로 테스트 가능 + +### 기각된 대안: 단일 Bot + 심볼 라우팅 + +하나의 TradingBot에서 `Dict[str, PositionState]`로 관리하는 방식. WebSocket 효율적이나 상태 머신 대규모 리팩토링 필요, 한 심볼 에러가 전체에 영향, 복잡도 대폭 증가. + +## 설계 상세 + +### 1. Config 변경 + +```python +# .env +SYMBOLS=XRPUSDT,TRXUSDT,DOGEUSDT +CORRELATION_SYMBOLS=BTCUSDT,ETHUSDT +MAX_SAME_DIRECTION=2 + +@dataclass +class Config: + symbols: list[str] # ["XRPUSDT", "TRXUSDT", "DOGEUSDT"] + correlation_symbols: list[str] # ["BTCUSDT", "ETHUSDT"] + max_same_direction: int # 같은 방향 최대 수 (기본 2) + # symbol: str 필드 제거 +``` + +- 기존 `SYMBOL` 환경변수 제거, `SYMBOLS`로 통일 +- `config.symbol` 참조하는 코드 모두 → 각 봇 인스턴스의 `self.symbol`로 전환 +- 하위호환: `SYMBOLS` 미설정 시 기존 `SYMBOL` 값을 1개짜리 리스트로 변환 + +### 2. 실행 구조 (main.py) + +```python +async def main(): + config = Config() + risk = RiskManager(config) # 공유 싱글턴 + + bots = [] + for symbol in config.symbols: + bot = TradingBot(config, symbol=symbol, risk=risk) + bots.append(bot) + + await asyncio.gather(*[bot.run() for bot in bots]) +``` + +- 각 봇은 독립적인 MultiSymbolStream, Exchange, UserDataStream 보유 +- RiskManager만 공유 + +### 3. TradingBot 생성자 변경 + +```python +class TradingBot: + def __init__(self, config: Config, symbol: str, risk: RiskManager): + self.symbol = symbol + self.config = config + self.exchange = BinanceFuturesClient(config, symbol=symbol) + self.risk = risk # 외부에서 주입 (공유) + self.ml_filter = MLFilter(model_dir=f"models/{symbol.lower()}") + ... +``` + +- `config.symbol` 의존 완전 제거 +- 각 봇이 자기 심볼을 직접 소유 + +### 4. Exchange 심볼 분리 + +```python +class BinanceFuturesClient: + def __init__(self, config: Config, symbol: str): + self.symbol = symbol # config.symbol → self.symbol +``` + +- 모든 API 호출에서 `self.config.symbol` → `self.symbol` + +### 5. RiskManager 공유 설계 + +```python +class RiskManager: + def __init__(self, config): + self.daily_pnl = 0.0 + self.open_positions: dict[str, str] = {} # {symbol: side} + self.max_positions = config.max_positions + self.max_same_direction = config.max_same_direction # 기본 2 + self._lock = asyncio.Lock() + + async def can_open_new_position(self, symbol: str, side: str) -> bool: + async with self._lock: + if len(self.open_positions) >= self.max_positions: + return False + if symbol in self.open_positions: + return False + same_dir = sum(1 for s in self.open_positions.values() if s == side) + if same_dir >= self.max_same_direction: + return False + return True + + async def register_position(self, symbol: str, side: str): + async with self._lock: + self.open_positions[symbol] = side + + async def close_position(self, symbol: str, pnl: float): + async with self._lock: + self.open_positions.pop(symbol, None) + self.daily_pnl += pnl + + def is_trading_allowed(self) -> bool: + # 글로벌 일일 손실 한도 체크 (기존과 동일) +``` + +- `asyncio.Lock()`으로 동시 접근 보호 +- 동일 방향 2개 제한으로 BTC 급락 시 3배 손실 방지 +- 마진은 심볼 수(N)로 균등 배분 + +### 6. 데이터 스트림 + +각 TradingBot이 자기만의 MultiSymbolStream 인스턴스를 가짐: + +``` +XRP Bot: [XRPUSDT, BTCUSDT, ETHUSDT] +TRX Bot: [TRXUSDT, BTCUSDT, ETHUSDT] +DOGE Bot: [DOGEUSDT, BTCUSDT, ETHUSDT] +``` + +- BTC/ETH 데이터 중복 수신되지만 격리성 확보 +- 각 stream의 primary_symbol이 달라 candle close 콜백 독립적 + +### 7. 모델 & 데이터 디렉토리 분리 + +``` +models/ +├── xrpusdt/ +│ ├── lgbm_filter.pkl +│ └── mlx_filter.weights.onnx +├── trxusdt/ +│ └── ... +└── dogeusdt/ + └── ... + +data/ +├── xrpusdt/ +│ └── combined_15m.parquet +├── trxusdt/ +│ └── combined_15m.parquet +└── dogeusdt/ + └── combined_15m.parquet +``` + +- 각 parquet: 해당 심볼이 primary + BTC/ETH가 correlation +- feature 구조 동일 (26 features) + +### 8. 학습 파이프라인 CLI 통일 + +모든 스크립트에 `--symbol`과 `--all` 패턴 적용: + +```bash +# 단일 심볼 +bash scripts/train_and_deploy.sh --symbol TRXUSDT +python scripts/fetch_history.py --symbol DOGEUSDT +python scripts/train_model.py --symbol TRXUSDT +python scripts/tune_hyperparams.py --symbol DOGEUSDT + +# 전체 심볼 +bash scripts/train_and_deploy.sh --all +bash scripts/train_and_deploy.sh # 인자 없으면 --all 동일 + +# MLX + 단일 심볼 +bash scripts/train_and_deploy.sh mlx --symbol DOGEUSDT +``` + +## 구현 순서 + +각 단계마다 기존 XRP 단일 모드로 테스트 가능하도록 점진적 전환: + +1. **Config** — `symbols` 리스트, `max_same_direction` 추가 +2. **RiskManager** — 공유 싱글턴, asyncio.Lock, 동일 방향 제한 +3. **exchange.py** — `config.symbol` → `self.symbol` 분리 +4. **bot.py** — 생성자에 `symbol`, `risk` 파라미터 추가, `config.symbol` 제거 +5. **main.py** — 심볼별 봇 인스턴스 생성 + `asyncio.gather()` +6. **학습 스크립트** — `--symbol`/`--all` CLI, 디렉토리 분리 + +## 변경 불필요한 컴포넌트 + +- `src/indicators.py` — 이미 심볼에 독립적 +- `src/notifier.py` — 이미 symbol 파라미터 수용 +- `src/user_data_stream.py` — 이미 심볼별 필터링 지원 +- `src/ml_features.py` — 이미 primary + auxiliary 구조 +- `src/label_builder.py` — 이미 범용적 diff --git a/docs/plans/2026-03-05-multi-symbol-trading-plan.md b/docs/plans/2026-03-05-multi-symbol-trading-plan.md new file mode 100644 index 0000000..1dcb706 --- /dev/null +++ b/docs/plans/2026-03-05-multi-symbol-trading-plan.md @@ -0,0 +1,920 @@ +# Multi-Symbol Trading Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** XRP 단일 심볼 거래 봇을 TRX·DOGE 등 다중 심볼 동시 거래로 확장한다. + +**Architecture:** 심볼별 독립 TradingBot 인스턴스를 `asyncio.gather()`로 병렬 실행. RiskManager만 공유 싱글턴으로 글로벌 리스크(일일 손실 한도, 동일 방향 제한)를 관리한다. 각 봇은 자기 심볼을 직접 소유하고, `config.symbol` 의존을 완전 제거한다. + +**Tech Stack:** Python asyncio, LightGBM, ONNX, Binance Futures API + +**Design Doc:** `docs/plans/2026-03-05-multi-symbol-trading-design.md` + +--- + +## Task 1: Config — `symbols` 리스트 추가, `symbol` 필드 유지(하위호환) + +**Files:** +- Modify: `src/config.py` +- Modify: `tests/test_config.py` +- Modify: `.env.example` + +**Step 1: Write the failing tests** + +`tests/test_config.py`에 다음 테스트를 추가: + +```python +def test_config_loads_symbols_list(): + """SYMBOLS 환경변수로 쉼표 구분 리스트를 로드한다.""" + os.environ["SYMBOLS"] = "XRPUSDT,TRXUSDT,DOGEUSDT" + os.environ.pop("SYMBOL", None) + cfg = Config() + assert cfg.symbols == ["XRPUSDT", "TRXUSDT", "DOGEUSDT"] + + +def test_config_fallback_to_symbol(): + """SYMBOLS 미설정 시 SYMBOL에서 1개짜리 리스트로 변환한다.""" + os.environ.pop("SYMBOLS", None) + os.environ["SYMBOL"] = "XRPUSDT" + cfg = Config() + assert cfg.symbols == ["XRPUSDT"] + + +def test_config_correlation_symbols(): + """상관관계 심볼 로드.""" + os.environ["CORRELATION_SYMBOLS"] = "BTCUSDT,ETHUSDT" + cfg = Config() + assert cfg.correlation_symbols == ["BTCUSDT", "ETHUSDT"] + + +def test_config_max_same_direction_default(): + """동일 방향 최대 수 기본값 2.""" + cfg = Config() + assert cfg.max_same_direction == 2 +``` + +**Step 2: Run tests to verify they fail** + +Run: `pytest tests/test_config.py -v` +Expected: FAIL — `Config` has no `symbols`, `correlation_symbols`, `max_same_direction` attributes + +**Step 3: Implement Config changes** + +`src/config.py`를 수정: + +```python +@dataclass +class Config: + api_key: str = "" + api_secret: str = "" + symbol: str = "XRPUSDT" + symbols: list = None # NEW + correlation_symbols: list = None # NEW + leverage: int = 10 + max_positions: int = 3 + max_same_direction: int = 2 # NEW + stop_loss_pct: float = 0.015 + take_profit_pct: float = 0.045 + trailing_stop_pct: float = 0.01 + discord_webhook_url: str = "" + margin_max_ratio: float = 0.50 + margin_min_ratio: float = 0.20 + margin_decay_rate: float = 0.0006 + ml_threshold: float = 0.55 + + def __post_init__(self): + self.api_key = os.getenv("BINANCE_API_KEY", "") + self.api_secret = os.getenv("BINANCE_API_SECRET", "") + self.symbol = os.getenv("SYMBOL", "XRPUSDT") + self.leverage = int(os.getenv("LEVERAGE", "10")) + self.discord_webhook_url = os.getenv("DISCORD_WEBHOOK_URL", "") + self.margin_max_ratio = float(os.getenv("MARGIN_MAX_RATIO", "0.50")) + self.margin_min_ratio = float(os.getenv("MARGIN_MIN_RATIO", "0.20")) + self.margin_decay_rate = float(os.getenv("MARGIN_DECAY_RATE", "0.0006")) + self.ml_threshold = float(os.getenv("ML_THRESHOLD", "0.55")) + self.max_same_direction = int(os.getenv("MAX_SAME_DIRECTION", "2")) + + # symbols: SYMBOLS 환경변수 우선, 없으면 SYMBOL에서 변환 + symbols_env = os.getenv("SYMBOLS", "") + if symbols_env: + self.symbols = [s.strip() for s in symbols_env.split(",") if s.strip()] + else: + self.symbols = [self.symbol] + + # correlation_symbols + corr_env = os.getenv("CORRELATION_SYMBOLS", "BTCUSDT,ETHUSDT") + self.correlation_symbols = [s.strip() for s in corr_env.split(",") if s.strip()] +``` + +`.env.example`에 추가: + +``` +SYMBOLS=XRPUSDT +CORRELATION_SYMBOLS=BTCUSDT,ETHUSDT +MAX_SAME_DIRECTION=2 +``` + +**Step 4: Run tests to verify they pass** + +Run: `pytest tests/test_config.py -v` +Expected: ALL PASS + +**Step 5: Run full test suite to verify no regressions** + +Run: `bash scripts/run_tests.sh` +Expected: ALL PASS (기존 코드는 `config.symbol`을 여전히 사용 가능하므로 깨지지 않음) + +**Step 6: Commit** + +```bash +git add src/config.py tests/test_config.py .env.example +git commit -m "feat: add multi-symbol config (symbols list, correlation_symbols, max_same_direction)" +``` + +--- + +## Task 2: RiskManager — 공유 싱글턴, asyncio.Lock, 동일 방향 제한 + +**Files:** +- Modify: `src/risk_manager.py` +- Modify: `tests/test_risk_manager.py` + +**Step 1: Write the failing tests** + +`tests/test_risk_manager.py`에 추가: + +```python +import asyncio + + +@pytest.fixture +def shared_risk(config): + config.max_same_direction = 2 + return RiskManager(config) + + +@pytest.mark.asyncio +async def test_can_open_new_position_async(shared_risk): + """비동기 포지션 오픈 허용 체크.""" + assert await shared_risk.can_open_new_position("XRPUSDT", "LONG") is True + + +@pytest.mark.asyncio +async def test_register_and_close_position(shared_risk): + """포지션 등록 후 닫기.""" + await shared_risk.register_position("XRPUSDT", "LONG") + assert "XRPUSDT" in shared_risk.open_positions + await shared_risk.close_position("XRPUSDT", pnl=1.5) + assert "XRPUSDT" not in shared_risk.open_positions + assert shared_risk.daily_pnl == 1.5 + + +@pytest.mark.asyncio +async def test_same_symbol_blocked(shared_risk): + """같은 심볼 중복 진입 차단.""" + await shared_risk.register_position("XRPUSDT", "LONG") + assert await shared_risk.can_open_new_position("XRPUSDT", "SHORT") is False + + +@pytest.mark.asyncio +async def test_max_same_direction_limit(shared_risk): + """같은 방향 2개 초과 차단.""" + await shared_risk.register_position("XRPUSDT", "LONG") + await shared_risk.register_position("TRXUSDT", "LONG") + # 3번째 LONG 차단 + assert await shared_risk.can_open_new_position("DOGEUSDT", "LONG") is False + # SHORT은 허용 + assert await shared_risk.can_open_new_position("DOGEUSDT", "SHORT") is True + + +@pytest.mark.asyncio +async def test_max_positions_global_limit(shared_risk): + """전체 포지션 수 한도 초과 차단.""" + shared_risk.config.max_positions = 2 + await shared_risk.register_position("XRPUSDT", "LONG") + await shared_risk.register_position("TRXUSDT", "SHORT") + assert await shared_risk.can_open_new_position("DOGEUSDT", "LONG") is False +``` + +**Step 2: Run tests to verify they fail** + +Run: `pytest tests/test_risk_manager.py -v -k "async or register or same_direction"` +Expected: FAIL — `can_open_new_position`이 sync이고 파라미터가 없음 + +**Step 3: Implement RiskManager changes** + +`src/risk_manager.py` 전체 교체: + +```python +import asyncio +from loguru import logger +from src.config import Config + + +class RiskManager: + def __init__(self, config: Config, max_daily_loss_pct: float = 0.05): + self.config = config + self.max_daily_loss_pct = max_daily_loss_pct + self.daily_pnl: float = 0.0 + self.initial_balance: float = 0.0 + self.open_positions: dict[str, str] = {} # {symbol: side} + self._lock = asyncio.Lock() + + def is_trading_allowed(self) -> bool: + """일일 최대 손실 초과 시 거래 중단""" + if self.initial_balance <= 0: + return True + loss_pct = abs(self.daily_pnl) / self.initial_balance + if self.daily_pnl < 0 and loss_pct >= self.max_daily_loss_pct: + logger.warning( + f"일일 손실 한도 초과: {loss_pct:.2%} >= {self.max_daily_loss_pct:.2%}" + ) + return False + return True + + async def can_open_new_position(self, symbol: str, side: str) -> bool: + """포지션 오픈 가능 여부 (전체 한도 + 중복 진입 + 동일 방향 제한)""" + async with self._lock: + if len(self.open_positions) >= self.config.max_positions: + logger.info(f"최대 포지션 수 도달: {len(self.open_positions)}/{self.config.max_positions}") + return False + if symbol in self.open_positions: + logger.info(f"{symbol} 이미 포지션 보유 중") + return False + same_dir = sum(1 for s in self.open_positions.values() if s == side) + if same_dir >= self.config.max_same_direction: + logger.info(f"동일 방향({side}) 한도 도달: {same_dir}/{self.config.max_same_direction}") + return False + return True + + async def register_position(self, symbol: str, side: str): + """포지션 등록""" + async with self._lock: + self.open_positions[symbol] = side + logger.info(f"포지션 등록: {symbol} {side} (현재 {len(self.open_positions)}개)") + + async def close_position(self, symbol: str, pnl: float): + """포지션 닫기 + PnL 기록""" + async with self._lock: + self.open_positions.pop(symbol, None) + self.daily_pnl += pnl + logger.info(f"포지션 종료: {symbol}, PnL={pnl:+.4f}, 누적={self.daily_pnl:+.4f}") + + def record_pnl(self, pnl: float): + self.daily_pnl += pnl + logger.info(f"오늘 누적 PnL: {self.daily_pnl:.4f} USDT") + + def reset_daily(self): + """매일 자정 초기화""" + self.daily_pnl = 0.0 + logger.info("일일 PnL 초기화") + + def set_base_balance(self, balance: float) -> None: + """봇 시작 시 기준 잔고 설정""" + self.initial_balance = balance + + def get_dynamic_margin_ratio(self, balance: float) -> float: + """잔고에 따라 선형 감소하는 증거금 비율 반환""" + ratio = self.config.margin_max_ratio - ( + (balance - self.initial_balance) * self.config.margin_decay_rate + ) + return max(self.config.margin_min_ratio, min(self.config.margin_max_ratio, ratio)) +``` + +주요 변경: +- `open_positions: list` → `dict[str, str]` (심볼→방향 매핑) +- `can_open_new_position()` → `async` + `symbol`, `side` 파라미터 +- `register_position()`, `close_position()` 새 메서드 추가 +- `asyncio.Lock()` 동시성 보호 + +**Step 4: Fix existing tests that break** + +기존 테스트에서 `can_open_new_position()` 호출 방식이 바뀌었으므로 수정: + +`tests/test_risk_manager.py`의 `test_position_size_capped`를 수정: + +```python +@pytest.mark.asyncio +async def test_position_size_capped(config): + rm = RiskManager(config, max_daily_loss_pct=0.05) + await rm.register_position("XRPUSDT", "LONG") + await rm.register_position("TRXUSDT", "SHORT") + await rm.register_position("DOGEUSDT", "LONG") + assert await rm.can_open_new_position("SOLUSDT", "SHORT") is False +``` + +**Step 5: Run tests to verify they pass** + +Run: `pytest tests/test_risk_manager.py -v` +Expected: ALL PASS + +**Step 6: Run full test suite** + +Run: `bash scripts/run_tests.sh` +Expected: `test_bot.py`에서 `can_open_new_position()` 호출이 깨질 수 있음 — Task 4에서 수정할 것이므로 지금은 bot 테스트 실패 허용 + +**Step 7: Commit** + +```bash +git add src/risk_manager.py tests/test_risk_manager.py +git commit -m "feat: shared RiskManager with async lock, same-direction limit, per-symbol tracking" +``` + +--- + +## Task 3: Exchange — `config.symbol` → `self.symbol` 분리 + +**Files:** +- Modify: `src/exchange.py` +- Modify: `tests/test_exchange.py` + +**Step 1: Write the failing test** + +`tests/test_exchange.py`에 추가: + +```python +def test_exchange_uses_own_symbol(): + """Exchange 클라이언트가 config.symbol 대신 생성자의 symbol을 사용한다.""" + os.environ.update({ + "BINANCE_API_KEY": "test_key", + "BINANCE_API_SECRET": "test_secret", + "SYMBOL": "XRPUSDT", + }) + config = Config() + with patch("src.exchange.Client"): + client = BinanceFuturesClient(config, symbol="TRXUSDT") + assert client.symbol == "TRXUSDT" +``` + +**Step 2: Run test to verify it fails** + +Run: `pytest tests/test_exchange.py::test_exchange_uses_own_symbol -v` +Expected: FAIL — `__init__` doesn't accept `symbol` parameter + +**Step 3: Implement Exchange changes** + +`src/exchange.py` 생성자 변경: + +```python +class BinanceFuturesClient: + def __init__(self, config: Config, symbol: str = None): + self.config = config + self.symbol = symbol or config.symbol + self.client = Client( + api_key=config.api_key, + api_secret=config.api_secret, + ) +``` + +모든 `self.config.symbol` 참조를 `self.symbol`로 교체 (9곳): +- Line 34: `set_leverage` → `symbol=self.symbol` +- Line 71: `place_order` params → `symbol=self.symbol` +- Line 101: `_place_algo_order` params → `symbol=self.symbol` +- Line 123: `get_position` → `symbol=self.symbol` +- Line 137: `cancel_all_orders` 일반 → `symbol=self.symbol` +- Line 144: `cancel_all_orders` algo → `symbol=self.symbol` +- Line 156: `get_open_interest` → `symbol=self.symbol` +- Line 169: `get_funding_rate` → `symbol=self.symbol` +- Line 183: `get_oi_history` → `symbol=self.symbol` + +**Step 4: Fix existing test fixtures** + +기존 `exchange` 픽스처에서 `BinanceFuturesClient.__new__`를 사용하는 곳에 `c.symbol` 설정 추가: + +```python +@pytest.fixture +def client(): + config = Config() + config.leverage = 10 + c = BinanceFuturesClient.__new__(BinanceFuturesClient) + c.config = config + c.symbol = config.symbol # NEW + return c + + +@pytest.fixture +def exchange(): + os.environ.update({ + "BINANCE_API_KEY": "test_key", + "BINANCE_API_SECRET": "test_secret", + "SYMBOL": "XRPUSDT", + "LEVERAGE": "10", + }) + config = Config() + c = BinanceFuturesClient.__new__(BinanceFuturesClient) + c.config = config + c.symbol = config.symbol # NEW + c.client = MagicMock() + return c +``` + +**Step 5: Run tests to verify they pass** + +Run: `pytest tests/test_exchange.py -v` +Expected: ALL PASS + +**Step 6: Commit** + +```bash +git add src/exchange.py tests/test_exchange.py +git commit -m "feat: exchange client accepts explicit symbol parameter, removes config.symbol dependency" +``` + +--- + +## Task 4: TradingBot — 생성자에 `symbol`, `risk` 주입 + +**Files:** +- Modify: `src/bot.py` +- Modify: `tests/test_bot.py` + +**Step 1: Write the failing tests** + +`tests/test_bot.py`에 추가: + +```python +def test_bot_accepts_symbol_and_risk(config): + """TradingBot이 symbol과 risk를 외부에서 주입받을 수 있다.""" + from src.risk_manager import RiskManager + risk = RiskManager(config) + with patch("src.bot.BinanceFuturesClient"): + bot = TradingBot(config, symbol="TRXUSDT", risk=risk) + assert bot.symbol == "TRXUSDT" + assert bot.risk is risk + + +def test_bot_stream_uses_injected_symbol(config): + """봇의 stream이 주입된 심볼을 primary로 사용한다.""" + from src.risk_manager import RiskManager + risk = RiskManager(config) + with patch("src.bot.BinanceFuturesClient"): + bot = TradingBot(config, symbol="DOGEUSDT", risk=risk) + assert "dogeusdt" in bot.stream.buffers + + +def test_bot_ml_filter_uses_symbol_model_dir(config): + """봇의 MLFilter가 심볼별 모델 디렉토리를 사용한다.""" + from src.risk_manager import RiskManager + risk = RiskManager(config) + with patch("src.bot.BinanceFuturesClient"): + bot = TradingBot(config, symbol="TRXUSDT", risk=risk) + assert "trxusdt" in str(bot.ml_filter._onnx_path) + assert "trxusdt" in str(bot.ml_filter._lgbm_path) +``` + +**Step 2: Run tests to verify they fail** + +Run: `pytest tests/test_bot.py -v -k "accepts_symbol or injected_symbol or symbol_model_dir"` +Expected: FAIL — `TradingBot.__init__` doesn't accept `symbol` or `risk` + +**Step 3: Implement TradingBot changes** + +`src/bot.py`의 `__init__` 변경: + +```python +class TradingBot: + def __init__(self, config: Config, symbol: str = None, risk: RiskManager = None): + self.config = config + self.symbol = symbol or config.symbol + self.exchange = BinanceFuturesClient(config, symbol=self.symbol) + self.notifier = DiscordNotifier(config.discord_webhook_url) + self.risk = risk or RiskManager(config) + self.ml_filter = MLFilter( + onnx_path=f"models/{self.symbol.lower()}/mlx_filter.weights.onnx", + lgbm_path=f"models/{self.symbol.lower()}/lgbm_filter.pkl", + threshold=config.ml_threshold, + ) + self.current_trade_side: str | None = None + self._entry_price: float | None = None + self._entry_quantity: float | None = None + self._is_reentering: bool = False + self._prev_oi: float | None = None + self._oi_history: deque = deque(maxlen=5) + self._latest_ret_1: float = 0.0 + self.stream = MultiSymbolStream( + symbols=[self.symbol] + config.correlation_symbols, + interval="15m", + on_candle=self._on_candle_closed, + ) +``` + +`_on_candle_closed` 변경: + +```python + async def _on_candle_closed(self, candle: dict): + primary_df = self.stream.get_dataframe(self.symbol) + btc_df = self.stream.get_dataframe("BTCUSDT") + eth_df = self.stream.get_dataframe("ETHUSDT") + if primary_df is not None: + await self.process_candle(primary_df, btc_df=btc_df, eth_df=eth_df) +``` + +`process_candle`에서 `can_open_new_position` 호출 변경 (2곳): + +```python +# Line ~138 (신규 진입): +if not await self.risk.can_open_new_position(self.symbol, raw_signal): + logger.info(f"[{self.symbol}] 포지션 오픈 불가") + return + +# Line ~322 (_close_and_reenter 내): +if not await self.risk.can_open_new_position(self.symbol, signal): + logger.info(f"[{self.symbol}] 최대 포지션 수 도달 — 재진입 건너뜀") + return +``` + +`_open_position`에서 `register_position` 호출 추가: + +```python + async def _open_position(self, signal: str, df): + balance = await self.exchange.get_balance() + # 심볼 수로 마진 균등 배분 + num_symbols = len(self.config.symbols) + per_symbol_balance = balance / num_symbols + price = df["close"].iloc[-1] + margin_ratio = self.risk.get_dynamic_margin_ratio(balance) + quantity = self.exchange.calculate_quantity( + balance=per_symbol_balance, price=price, + leverage=self.config.leverage, margin_ratio=margin_ratio, + ) + # ... 기존 로직 ... + + # 포지션 등록 + await self.risk.register_position(self.symbol, signal) + self.current_trade_side = signal + # ... 나머지 동일 ... +``` + +`_on_position_closed`에서 `close_position` 호출: + +```python + async def _on_position_closed(self, net_pnl, close_reason, exit_price): + # ... 기존 PnL 계산 로직 ... + await self.risk.close_position(self.symbol, net_pnl) + # record_pnl 제거 (close_position 내에서 처리) + # ... 나머지 동일 ... +``` + +모든 `self.config.symbol` 참조를 `self.symbol`로 교체 (6곳): +- Line 31 → `self.symbol` (stream symbols) +- Line 37 → `self.symbol` (get_dataframe) +- Line 197 → `self.symbol` (notify_open) +- Line 251 → `self.symbol` (notify_close) +- Line 340 → `self.symbol` (run 로그) +- Line 348 → `self.symbol` (UserDataStream) + +`run()` 메서드의 로그도 변경: + +```python + async def run(self): + logger.info(f"[{self.symbol}] 봇 시작, 레버리지 {self.config.leverage}x") + # ... 나머지 동일, self.config.symbol → self.symbol ... +``` + +**Step 4: Fix existing bot tests** + +기존 `tests/test_bot.py`의 모든 `TradingBot(config)` 호출은 하위호환되므로 그대로 동작. +단, `risk.can_open_new_position` 호출이 async로 바뀌었으므로 mock 수정 필요: + +`test_close_and_reenter_calls_open_when_ml_passes`: +```python + bot.risk = MagicMock() + bot.risk.can_open_new_position = AsyncMock(return_value=True) +``` + +`test_close_and_reenter_skips_open_when_max_positions_reached`: +```python + bot.risk = MagicMock() + bot.risk.can_open_new_position = AsyncMock(return_value=False) +``` + +`test_bot_processes_signal`에서 `bot.risk`도 mock: +```python + bot.risk = MagicMock() + bot.risk.is_trading_allowed.return_value = True + bot.risk.can_open_new_position = AsyncMock(return_value=True) + bot.risk.register_position = AsyncMock() + bot.risk.get_dynamic_margin_ratio.return_value = 0.50 +``` + +**Step 5: Run tests to verify they pass** + +Run: `pytest tests/test_bot.py -v` +Expected: ALL PASS + +**Step 6: Run full test suite** + +Run: `bash scripts/run_tests.sh` +Expected: ALL PASS + +**Step 7: Commit** + +```bash +git add src/bot.py tests/test_bot.py +git commit -m "feat: TradingBot accepts symbol and shared RiskManager, removes config.symbol dependency" +``` + +--- + +## Task 5: main.py — 심볼별 봇 인스턴스 생성 + asyncio.gather + +**Files:** +- Modify: `main.py` + +**Step 1: Implement main.py changes** + +```python +import asyncio +from dotenv import load_dotenv +from src.config import Config +from src.bot import TradingBot +from src.risk_manager import RiskManager +from src.logger_setup import setup_logger +from loguru import logger + +load_dotenv() + + +async def main(): + setup_logger(log_level="INFO") + config = Config() + risk = RiskManager(config) + + bots = [] + for symbol in config.symbols: + bot = TradingBot(config, symbol=symbol, risk=risk) + bots.append(bot) + + logger.info(f"멀티심볼 봇 시작: {config.symbols} ({len(bots)}개 인스턴스)") + await asyncio.gather(*[bot.run() for bot in bots]) + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +**Step 2: Run full test suite to verify no regressions** + +Run: `bash scripts/run_tests.sh` +Expected: ALL PASS + +**Step 3: Commit** + +```bash +git add main.py +git commit -m "feat: main.py spawns per-symbol TradingBot instances with shared RiskManager" +``` + +--- + +## Task 6: MLFilter — 심볼별 모델 디렉토리 폴백 + +**Files:** +- Modify: `src/ml_filter.py` + +**Step 1: Implement MLFilter path fallback** + +MLFilter는 이미 `onnx_path`/`lgbm_path`를 생성자에서 받으므로, bot.py에서 심볼별 경로를 주입하면 된다 (Task 4에서 완료). + +다만 기존 `models/lgbm_filter.pkl` 경로에 모델이 있는 경우(단일 심볼 환경)에도 동작하도록, 심볼별 디렉토리에 모델이 없으면 루트 `models/`에서 폴백하는 로직을 `bot.py`에 추가: + +`src/bot.py`의 `__init__`에서: + +```python + # 심볼별 모델 디렉토리. 없으면 기존 models/ 루트로 폴백 + symbol_model_dir = Path(f"models/{self.symbol.lower()}") + if symbol_model_dir.exists(): + onnx_path = str(symbol_model_dir / "mlx_filter.weights.onnx") + lgbm_path = str(symbol_model_dir / "lgbm_filter.pkl") + else: + onnx_path = "models/mlx_filter.weights.onnx" + lgbm_path = "models/lgbm_filter.pkl" + self.ml_filter = MLFilter( + onnx_path=onnx_path, + lgbm_path=lgbm_path, + threshold=config.ml_threshold, + ) +``` + +**Step 2: Run full test suite** + +Run: `bash scripts/run_tests.sh` +Expected: ALL PASS + +**Step 3: Commit** + +```bash +git add src/bot.py +git commit -m "feat: MLFilter falls back to models/ root if symbol-specific dir not found" +``` + +--- + +## Task 7: 학습 스크립트 — `--symbol` / `--all` CLI 통일 + +**Files:** +- Modify: `scripts/fetch_history.py` +- Modify: `scripts/train_model.py` +- Modify: `scripts/tune_hyperparams.py` +- Modify: `scripts/train_and_deploy.sh` +- Modify: `scripts/deploy_model.sh` + +### Step 1: fetch_history.py — `--symbol` 단일 심볼 + 출력 경로 자동 결정 + +`scripts/fetch_history.py`의 argparse에 `--symbol` 추가 및 `--output` 자동 결정: + +현재 사용법: `--symbols XRPUSDT BTCUSDT ETHUSDT --output data/combined_15m.parquet` + +변경 후: +```python +parser.add_argument("--symbol", type=str, default=None, + help="단일 거래 심볼 (예: TRXUSDT). 상관관계 심볼 자동 추가") +``` + +`--symbol TRXUSDT` 지정 시: +- `symbols = ["TRXUSDT", "BTCUSDT", "ETHUSDT"]` +- `output = "data/trxusdt/combined_15m.parquet"` (자동) + +`--symbols XRPUSDT BTCUSDT ETHUSDT` (기존 방식)도 유지. + +### Step 2: train_model.py — `--symbol` 추가 + +```python +parser.add_argument("--symbol", type=str, default=None, + help="학습 대상 심볼 (예: TRXUSDT). data/{symbol}/ 에서 데이터 로드, models/{symbol}/ 에 저장") +``` + +`--symbol TRXUSDT` 지정 시: +- 데이터: `data/trxusdt/combined_15m.parquet` +- 모델: `models/trxusdt/lgbm_filter.pkl` +- 로그: `models/trxusdt/training_log.json` + +`--data` 옵션이 명시되면 그것을 우선. + +### Step 3: tune_hyperparams.py — `--symbol` 추가 + +train_model.py와 동일한 패턴. `--symbol`이 지정되면: +- 데이터: `data/{symbol}/combined_15m.parquet` +- 결과: `models/{symbol}/tune_results_*.json` +- active params: `models/{symbol}/active_lgbm_params.json` + +### Step 4: train_and_deploy.sh — `--symbol` / `--all` 지원 + +```bash +# 사용법: +# bash scripts/train_and_deploy.sh [mlx|lgbm] [--symbol TRXUSDT] +# bash scripts/train_and_deploy.sh [mlx|lgbm] --all +# bash scripts/train_and_deploy.sh # --all과 동일 (기본값) +``` + +`--symbol` 지정 시: 해당 심볼만 fetch → train → deploy +`--all` 또는 인자 없음: `SYMBOLS` 환경변수의 모든 심볼 순차 처리 + +핵심 로직: +```bash +if [ -n "$SYMBOL_ARG" ]; then + TARGETS=("$SYMBOL_ARG") +else + # .env에서 SYMBOLS 로드 + TARGETS=($(python -c "from src.config import Config; c=Config(); print(' '.join(c.symbols))")) +fi + +for SYM in "${TARGETS[@]}"; do + SYM_LOWER=$(echo "$SYM" | tr '[:upper:]' '[:lower:]') + mkdir -p "data/$SYM_LOWER" "models/$SYM_LOWER" + + # fetch + python scripts/fetch_history.py --symbol "$SYM" ... + + # train + python scripts/train_model.py --symbol "$SYM" ... + + # deploy + bash scripts/deploy_model.sh "$BACKEND" --symbol "$SYM" +done +``` + +### Step 5: deploy_model.sh — `--symbol` 지원 + +```bash +# 사용법: bash scripts/deploy_model.sh [lgbm|mlx] [--symbol TRXUSDT] +``` + +`--symbol` 지정 시: +- 로컬: `models/{symbol}/lgbm_filter.pkl` +- 원격: `$LXC_MODELS_PATH/{symbol}/lgbm_filter.pkl` + +### Step 6: Run full test suite + +Run: `bash scripts/run_tests.sh` +Expected: ALL PASS (스크립트 변경은 unit test에 영향 없음) + +### Step 7: Smoke test 스크립트 + +```bash +# fetch만 소량 테스트 +python scripts/fetch_history.py --symbol TRXUSDT --interval 15m --days 1 +ls data/trxusdt/combined_15m.parquet # 파일 존재 확인 +``` + +### Step 8: Commit + +```bash +git add scripts/fetch_history.py scripts/train_model.py scripts/tune_hyperparams.py scripts/train_and_deploy.sh scripts/deploy_model.sh +git commit -m "feat: add --symbol/--all CLI to all training scripts for per-symbol pipeline" +``` + +--- + +## Task 8: 디렉토리 구조 생성 + .env.example 업데이트 + +**Files:** +- Create: `models/xrpusdt/.gitkeep` +- Create: `models/trxusdt/.gitkeep` +- Create: `models/dogeusdt/.gitkeep` +- Create: `data/xrpusdt/.gitkeep` +- Create: `data/trxusdt/.gitkeep` +- Create: `data/dogeusdt/.gitkeep` +- Modify: `.env.example` + +**Step 1: Create directory structure** + +```bash +mkdir -p models/{xrpusdt,trxusdt,dogeusdt} +mkdir -p data/{xrpusdt,trxusdt,dogeusdt} +touch models/{xrpusdt,trxusdt,dogeusdt}/.gitkeep +touch data/{xrpusdt,trxusdt,dogeusdt}/.gitkeep +``` + +**Step 2: Update .env.example** + +``` +BINANCE_API_KEY= +BINANCE_API_SECRET= +SYMBOLS=XRPUSDT +CORRELATION_SYMBOLS=BTCUSDT,ETHUSDT +LEVERAGE=10 +RISK_PER_TRADE=0.02 +DISCORD_WEBHOOK_URL= +ML_THRESHOLD=0.55 +MAX_SAME_DIRECTION=2 +BINANCE_TESTNET_API_KEY= +BINANCE_TESTNET_API_SECRET= +``` + +**Step 3: Commit** + +```bash +git add models/ data/ .env.example +git commit -m "feat: add per-symbol model/data directories and update .env.example" +``` + +--- + +## Task 9: 기존 모델 마이그레이션 안내 + 문서 업데이트 + +**Files:** +- Modify: `CLAUDE.md` + +**Step 1: Update CLAUDE.md** + +Architecture 섹션에 멀티심볼 관련 내용 추가: + +- `main.py` → `Config` → 심볼별 `TradingBot` 인스턴스 → `asyncio.gather()` +- `RiskManager` 공유 싱글턴 (글로벌 일일 손실 + 동일 방향 제한) +- 모델/데이터 디렉토리: `models/{symbol}/`, `data/{symbol}/` + +Common Commands 섹션 업데이트: + +```bash +# 단일 심볼 학습 +bash scripts/train_and_deploy.sh --symbol TRXUSDT + +# 전체 심볼 학습 +bash scripts/train_and_deploy.sh --all +``` + +**Step 2: Commit** + +```bash +git add CLAUDE.md +git commit -m "docs: update architecture and commands for multi-symbol trading" +``` + +--- + +## 구현 순서 요약 + +| Task | 내용 | 의존성 | +|------|------|--------| +| 1 | Config: `symbols`, `correlation_symbols`, `max_same_direction` | 없음 | +| 2 | RiskManager: 공유 싱글턴, async Lock, 동일 방향 제한 | Task 1 | +| 3 | Exchange: `self.symbol` 분리 | 없음 (Task 1과 병렬 가능) | +| 4 | TradingBot: `symbol`, `risk` 주입, `config.symbol` 제거 | Task 1, 2, 3 | +| 5 | main.py: 심볼별 봇 생성 + gather | Task 4 | +| 6 | MLFilter: 심볼별 모델 디렉토리 폴백 | Task 4 | +| 7 | 학습 스크립트: `--symbol` / `--all` CLI | Task 1 | +| 8 | 디렉토리 구조 + .env.example | 없음 | +| 9 | 문서 업데이트 | 전체 완료 후 | + +각 태스크 완료 후 기존 XRP 단일 모드에서 전체 테스트를 통과해야 한다.