kis_trader — 통합 트레이딩 봇
스캘핑(SCALP) + 꼬리잡기(SHORT, Tail Catch) 두 전략을 단일 프로세스에서
각자 독립 쓰레드로 돌리는 통합 봇. KIS REST/WebSocket 호출을 단일 허브로
묶고, 주문은 단일 OrderManager 를 경유해 ODNO 기반으로 추적한다.
디렉터리
kis_trader/
├── main.py # 오케스트레이터 (각 전략을 쓰레드로 기동)
├── utils/
│ ├── env.py # env_config (DB) + os.environ 통합 조회
│ ├── logger.py # 공용 로거 / 안전 JSON 저장 / 알림(MM/TG)
│ └── request_handler.py # SafeRequest: rate-limit + 재시도
├── network/
│ └── ws_manager.py # 단일 WS 허브 (kis_ws 재사용, 구독 ref-counting)
├── strategies/
│ ├── base.py # BaseStrategy (threading.Thread)
│ ├── scalping.py # scalping_engine 래퍼
│ └── tail_catch.py # tail_engine 래퍼
├── execution/
│ ├── kis_client.py # 통합 KIS REST 클라이언트 (ODNO 반환)
│ └── order_manager.py # Master Executor (종목 Lock + 실잔고검증)
├── database/
│ └── db_manager.py # TradeDBExt: 기존 TradeDB + orders 테이블
└── backtest/
└── backtest_web.py # 기존 backtest_web.py 재호출 래퍼
아키텍처 한 눈에
[SCALP 쓰레드] ──┐
│─▶ OrderRequest ─▶ OrderManager ─▶ KISClient ─▶ KIS API
[SHORT 쓰레드] ──┘ │ │ │
│ │ └── DB(orders) ← ODNO PK
│ └───── DB(active_trades, trade_history)
└──────── 실잔고 검증 (get_broker_holdings)
공유 인프라 (1개 인스턴스)
• KISClient : 토큰/Throttle/재시도
• WSManager : 단일 WS 세션, 구독 ref counting
• TradeDBExt : orders 테이블 + 기존 TradeDB
• OrderManager : 종목 Lock, 동일 종목 다전략 정책, ODNO 저장
왜 이 구조인가
| 기존 문제 | 새 구조에서의 해결 |
|---|---|
봇이 잡고 있는 holdings 가 실제 계좌와 어긋남 |
매도/매수 직전 OrderManager.get_broker_holdings(force=True) 호출로 실잔고 검증 |
| 두 봇이 같은 종목에 동시 매수 → 이중 포지션 | OrderManager._code_locks[code] 로 직렬화 + orders 테이블 UNIQUE(strategy,code,side,date) |
| 주문번호(ODNO) 미저장 → 사후 추적 불가 | kis_client._order() 가 ODNO 반환 → TradeDBExt.insert_order() 로 PK 저장 |
| 토큰 재발급 경합 / REST 호출 폭주 | KISClient 하나 + kis_token_manager 공유 + SafeRequest 쿨다운 |
| 두 봇이 WS 각자 → 구독 수/approval_key 경합 | WSManager 단일 세션 + 구독 레퍼런스 카운팅 |
| 설정 하드코딩 | 모든 값은 env_config → os.environ → 기본값 순으로 조회 |
실행
cd ~/kis_bot
# 기본(두 전략 모두 ON)
python -m kis_trader.main
# 스캘핑만
STRATEGY_SCALP_ENABLED=true STRATEGY_SHORT_ENABLED=false python -m kis_trader.main
# 꼬리잡기만
STRATEGY_SCALP_ENABLED=false STRATEGY_SHORT_ENABLED=true python -m kis_trader.main
주요 환경변수
| 이름 | 기본 | 설명 |
|---|---|---|
STRATEGY_SCALP_ENABLED |
true |
스캘핑 전략 활성화 |
STRATEGY_SHORT_ENABLED |
true |
꼬리잡기 전략 활성화 |
STRATEGY_SAME_CODE_POLICY |
block |
같은 종목을 다른 전략이 이미 보유 중일 때 block(차단) / allow(허용) |
REAL_BALANCE_VERIFY_BEFORE_BUY |
true |
매수 전 실 잔고 재조회 |
REAL_BALANCE_VERIFY_BEFORE_SELL |
true |
매도 전 실 잔고 재조회 (0주면 active_trades 정리) |
MAX_STOCKS |
3 |
전략당 동시 보유 최대 종목 수 |
REENTRY_COOLDOWN_SEC |
300 |
매도 후 같은 종목 재진입 쿨다운(초) |
WS_TIMEFRAMES |
1,3,15,60 |
WS 봉 집계 타임프레임(분) |
PERMANENT_WS_CODES |
069500,229200 |
WS 영구 구독 코드(쉼표) |
SCALP_STOP_LOSS_PCT / SCALP_TAKE_PROFIT_PCT |
-0.015 / 0.015 |
스캘핑 손절/익절 비율 |
STOP_LOSS_PCT / TAKE_PROFIT_PCT |
-0.04 / 0.05 |
꼬리잡기 손절/익절 비율 |
MAX_LOSS_PER_TRADE_KRW |
200000 |
1회 거래 최대 손실 허용액(원) |
SLOT_MONEY_DEFAULT |
3000000 |
1슬롯 기본 투자 금액(원) |
전략 ON/OFF 동작 방식
TradingOrchestrator 는 시작 시 STRATEGY_*_ENABLED 를 읽어서 해당 전략 클래스를
쓰레드로 등록한다. 따라서:
- 꼬리잡기만 끄고 싶을 때 →
env_config또는 OS env 에STRATEGY_SHORT_ENABLED=false - 재시작 필요 (동작 중 on/off 전환은 지원 안 함, 대신 공격적 재시작 스크립트 사용)
백테스트
python -m kis_trader.backtest.backtest_web
엔진(scalping_engine.py, tail_engine.py) 자체를 공유하므로 백테스트와 실매매
신호는 100% 동일 로직이다.
주의사항
- 프로젝트 루트의 기존 파일 (
scalping_engine.py,tail_engine.py,kis_ws.py,kis_token_manager.py,risk_manager.py,database.py등) 을 그대로 사용한다.kis_trader/는 이들을 조립하는 얇은 래퍼 층이다. - DB 스키마에
orders테이블이 자동 생성된다 (TradeDBExt._ensure_orders_table). - 기존
kis_scalping_ver2.py/kis_short_ver3.py는 남겨두되, 중복 실행 금지 (계좌/토큰/WS 경합).