kis_trader/kiwwom_trader/README.md

kiwwom_trader

키움 REST API + 웹소켓 기반 스캘핑 봇. KIS kis_scalping_ver2와 동일한 로직·구조를 유지하며, 키움 증권 API로 전환한 버전입니다.

폴더 이전 후에도 동작하도록

• 프로젝트 루트: KIWOOM_TRADER_ROOT 환경변수로 지정 가능. 미설정 시 이 폴더(kiwwom_trader) 기준.
• kiwoom_rest_api: 이 폴더의 상위 디렉터리 또는 형제 디렉터리에 두면 자동으로 import됩니다.
  • 예: /home/hoon/kiwwom_trader + /home/hoon/kiwoom_rest_api
• database, scalping_engine (kis_bot): KIS_BOT_PATH 환경변수로 kis_bot 루트 지정.
  • 예: export KIS_BOT_PATH=/home/hoon/kis_bot
  • 미설정 시 상위의 kis_bot 폴더를 참조합니다.

실행

# kiwwom_trader 폴더에서
python run.py

이전 후 예시:

export KIWOOM_TRADER_ROOT=/home/hoon/kiwwom_trader
export KIS_BOT_PATH=/home/hoon/kis_bot
cd /home/hoon/kiwwom_trader
python run.py

구성

파일	역할
config.py	ROOT·경로 독립, sys.path 설정, .env 로드
run.py	진입점
scalping_bot.py	키움 REST(주문/조회) + 매수신호(scalping_engine) 메인 루프
ws_candle_agg.py	웹소켓 실시간 체결(0B) → 1분봉 집계 (필요 시 봇에서 연결)

웹소켓

키움 웹소켓 실시간 타입 0B(주식체결) 를 구독하면 1분봉을 메모리/DB에 쌓을 수 있습니다.
ws_candle_agg.py의 KiwoomCandleAggregator와 build_ws_client_with_candle_callback를 사용해,
봇 초기화 시 웹소켓 클라이언트를 띄우고 후보 종목 리스트로 등록하면 됩니다.
(현재 run() 루프는 REST 조회 + DB ws_candles 기준으로 동작합니다.)

의존성

• pip install -r requirements.txt (httpx 등 kiwoom_rest_api 의존성 포함)
• kiwoom_rest_api 패키지는 이 저장소의 kiwoom_rest_api 폴더를 상위/형제 경로에 두거나, PYTHONPATH에 추가해야 합니다.

인증

kiwoom_rest_api/.env 또는 이 폴더의 .env에 다음을 설정합니다.

• KIWOOM_API_KEY
• KIWOOM_API_SECRET
• KIWOOM_USE_SANDBOX (true/false)

DB(MariaDB) 접속은 kis_bot과 동일하게 DB_HOST, DB_USER, DB_PASS, DB_NAME 등 환경변수를 사용합니다.