docs: add kill switch, SOL symbol swap, and analysis tools to docs

- README: add kill switch section with Slow Bleed explanation, env vars
- README: update SYMBOLS to XRPUSDT,SOLUSDT,DOGEUSDT, add SOL params
- README: add compare_symbols.py and position_sizing_analysis.py to tree
- ARCHITECTURE: add Gate 0 (kill switch) to entry flow, update risk table
- ARCHITECTURE: add trade recording + kill check to TP/SL scenario
- ARCHITECTURE: update weekly report pipeline (7 steps with kill monitoring)
- CLAUDE.md: add kill switch description to architecture section

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
21in7
2026-03-19 00:04:06 +09:00
parent b86aa8b072
commit 24ed7ddec0
3 changed files with 78 additions and 27 deletions

View File

@@ -15,10 +15,12 @@ Binance Futures 자동매매 봇. 복합 기술 지표와 ML 필터(LightGBM / M
- **ATR 기반 손절/익절**: 변동성에 따라 동적으로 SL/TP 계산, 환경변수로 배수 조절
- **반대 시그널 재진입**: 보유 포지션과 반대 신호 발생 시 즉시 청산 후 재진입
- **리스크 관리**: 동일 방향 포지션 제한, 일일 손실 한도(5%), 동적 증거금 비율
- **듀얼 레이어 킬스위치**: Fast Kill(8연속 순손실) + Slow Kill(15거래 PF<0.75) — 심볼별 독립 차단, 기존 포지션 청산은 정상 작동
- **실시간 TP/SL 감지**: Binance User Data Stream으로 즉시 감지
- **Discord 알림**: 진입·청산·오류 이벤트 실시간 웹훅 알림
- **Discord 알림**: 진입·청산·킬스위치 발동·오류 이벤트 실시간 웹훅 알림
- **모니터링 대시보드**: 거래 내역, 수익 통계, 차트를 웹에서 조회
- **주간 전략 리포트**: 자동 성능 측정, 추이 추적, ML 재학습 시점 판단
- **주간 전략 리포트**: 자동 성능 측정, 추이 추적, 킬스위치 모니터링, ML 재학습 시점 판단
- **종목 비교 분석**: 심볼별 파라미터 sweep + Robust Monte Carlo 포지션 사이징
---
@@ -48,7 +50,7 @@ cp .env.example .env
# 필수
BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret
SYMBOLS=XRPUSDT # 거래할 심볼 (쉼표 구분, 예: XRPUSDT,TRXUSDT,DOGEUSDT)
SYMBOLS=XRPUSDT,SOLUSDT,DOGEUSDT # 거래할 심볼 (쉼표 구분)
# 권장
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
@@ -123,14 +125,15 @@ Discord 웹훅을 설정했다면 진입/청산 시 실시간 알림을 받게
**심볼별 오버라이드**: `{환경변수}_{심볼}` 형태로 심볼마다 독립 설정 가능. 미설정 시 전역 기본값 사용.
```env
# 예시: 2026-03-17 스윕 최적화 결과
# 예시: 스윕 최적화 결과
ATR_SL_MULT_XRPUSDT=1.5
ATR_TP_MULT_XRPUSDT=4.0
ADX_THRESHOLD_XRPUSDT=30
ATR_SL_MULT_TRXUSDT=2.0
ATR_TP_MULT_TRXUSDT=4.0
ADX_THRESHOLD_TRXUSDT=25
ATR_SL_MULT_SOLUSDT=1.0
ATR_TP_MULT_SOLUSDT=4.0
ADX_THRESHOLD_SOLUSDT=20
MARGIN_MAX_RATIO_SOLUSDT=0.08
ATR_SL_MULT_DOGEUSDT=2.0
ATR_TP_MULT_DOGEUSDT=2.0
@@ -158,10 +161,39 @@ ML 필터는 기술 지표 신호를 한 번 더 검증하여 오진입을 차
| `MARGIN_MIN_RATIO` | `0.20` | 최소 증거금 비율 (잔고 대비) |
| `MARGIN_DECAY_RATE` | `0.0006` | 잔고 증가 시 증거금 비율 감소 속도 |
- **일일 손실 한도**: 기준 잔고의 5% 초과 시 당일 거래 중단
- **일일 손실 한도**: 기준 잔고의 5% 초과 시 당일 거래 중단 (단일 충격 방어)
- **듀얼 레이어 킬스위치**: 구조적 엣지 소실에 의한 점진적 계좌 우하향(Slow Bleed) 방어
- **동적 증거금**: 잔고가 늘어날수록 비율을 선형으로 줄여 과노출 방지
- **포지션 복구**: 봇 재시작 시 기존 포지션 자동 감지 및 상태 복원
### 킬스위치
일일 손실 한도는 단일 충격 방어용이지, 누적 승률 하락 방어용이 아닙니다. 매일 한도 근처까지 손실을 내고 멈추는 패턴이 반복되면 한 달 뒤 계좌의 30~40%가 조용히 증발합니다. 킬스위치는 이 Slow Bleed를 자동으로 차단합니다.
| 레이어 | 조건 | 방어 대상 |
|--------|------|-----------|
| **Fast Kill** | 8연속 순손실 (net_pnl, 수수료 포함) | 급격한 전략 붕괴 |
| **Slow Kill** | 최근 15거래 Profit Factor < 0.75 | 점진적 엣지 소실 |
**동작 방식:**
- 심볼별 독립 제어: SOL이 킬되어도 XRP/DOGE는 정상 운영
- 진입만 차단: 기존 포지션의 SL/TP 청산은 정상 작동 (물린 상태 방치 방지)
- 거래 이력 persist: `data/trade_history/{symbol}.jsonl`에 매 청산마다 기록
- 봇 재시작 시 소급 검증: 이력 파일에서 마지막 15건을 읽어 킬스위치 상태 복원
- 수동 해제: `.env``RESET_KILL_SWITCH_{SYMBOL}=True` 추가 후 봇 재시작
**주간 리포트 모니터링:**
```
[킬스위치 모니터링]
XRP: 연속손실 2/8 | 15거래PF 1.42
SOL: 연속손실 0/8 | 15거래PF -.-- (3건)
DOGE: 연속손실 6/8 ⚠ | 15거래PF 0.71 🔴 KILLED
```
| 환경변수 | 설명 |
|---------|------|
| `RESET_KILL_SWITCH_{SYMBOL}` | `True`로 설정 후 재시작하면 해당 심볼 킬스위치 해제. 해제 후 반드시 제거할 것 |
---
## 대시보드
@@ -219,6 +251,8 @@ docker compose up -d
| `ADX_THRESHOLD_{SYMBOL}` | — | | 심볼별 ADX 필터 오버라이드 |
| `VOL_MULTIPLIER_{SYMBOL}` | — | | 심볼별 거래량 배수 오버라이드 |
| `DASHBOARD_API_URL` | `http://10.1.10.24:8000` | | 대시보드 API 주소 (주간 리포트용) |
| `MARGIN_MAX_RATIO_{SYMBOL}` | — | | 심볼별 최대 증거금 비율 오버라이드 |
| `RESET_KILL_SWITCH_{SYMBOL}` | — | | `True`로 설정 후 재시작하면 킬스위치 해제 (해제 후 반드시 제거) |
| `BINANCE_TESTNET_API_KEY` | — | | Testnet API 키 |
| `BINANCE_TESTNET_API_SECRET` | — | | Testnet API 시크릿 |
@@ -257,7 +291,9 @@ cointrader/
│ ├── train_and_deploy.sh # 전체 파이프라인 (--symbol / --all 지원)
│ ├── tune_hyperparams.py # Optuna 하이퍼파라미터 자동 탐색 (--symbol 지원)
│ ├── strategy_sweep.py # 전략 파라미터 그리드 스윕 (324개 조합)
│ ├── weekly_report.py # 주간 전략 리포트 (백테스트+대시보드API+추이+Discord)
│ ├── compare_symbols.py # 종목 비교 백테스트 (심볼별 파라미터 sweep)
│ ├── position_sizing_analysis.py # Robust Monte Carlo 포지션 사이징 분석
│ ├── weekly_report.py # 주간 전략 리포트 (백테스트+킬스위치+대시보드API+추이+Discord)
│ ├── run_backtest.py # 단일 백테스트 CLI
│ ├── deploy_model.sh # 모델 파일 LXC 서버 전송 (--symbol 지원)
│ └── run_tests.sh # 전체 테스트 실행
@@ -266,6 +302,7 @@ cointrader/
│ └── ui/ # React 프론트엔드 (Vite + Recharts)
├── models/ # 학습된 모델 저장 (심볼별 하위 디렉토리)
├── data/ # 과거 데이터 캐시 (심볼별 하위 디렉토리)
│ └── trade_history/ # 킬스위치용 실전 거래 이력 (심볼별 JSONL)
├── results/
│ └── weekly/ # 주간 리포트 JSON 저장
├── logs/ # 로그 파일