cointrader/docs/plans/2026-03-05-multi-symbol-trading-plan.md

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에 다음 테스트를 추가:

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를 수정:

@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

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에 추가:

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 전체 교체:

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를 수정:

@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

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에 추가:

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 생성자 변경:

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 설정 추가:

@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

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에 추가:

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__ 변경:

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 변경:

    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곳):

# 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 호출 추가:

    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 호출:

    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() 메서드의 로그도 변경:

    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:

    bot.risk = MagicMock()
    bot.risk.can_open_new_position = AsyncMock(return_value=True)

test_close_and_reenter_skips_open_when_max_positions_reached:

    bot.risk = MagicMock()
    bot.risk.can_open_new_position = AsyncMock(return_value=False)

test_bot_processes_signal에서 bot.risk도 mock:

    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

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

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

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__에서:

        # 심볼별 모델 디렉토리. 없으면 기존 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

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

변경 후:

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 추가

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 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 환경변수의 모든 심볼 순차 처리

핵심 로직:

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 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 스크립트

# fetch만 소량 테스트
python scripts/fetch_history.py --symbol TRXUSDT --interval 15m --days 1
ls data/trxusdt/combined_15m.parquet  # 파일 존재 확인

Step 8: Commit

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

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

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 scripts/train_and_deploy.sh --symbol TRXUSDT

# 전체 심볼 학습
bash scripts/train_and_deploy.sh --all

Step 2: Commit

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 단일 모드에서 전체 테스트를 통과해야 한다.