브랜치 분리 방식: A / B / C

A 선택 시 커밋 메시지: 위 초안 OK / 수정 / 직접 작성
작업 시점: 지금 / 운영 데이터 1~2일 쌓고 / 주말

kiwwom_trader/README.md

@@ -0,0 +1,59 @@
+# 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` 폴더를 참조합니다.
+
+## 실행
+
+```bash
+# kiwwom_trader 폴더에서
+python run.py
+```
+
+이전 후 예시:
+
+```bash
+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` 등 환경변수를 사용합니다.