249 lines
5.4 KiB
Markdown
249 lines
5.4 KiB
Markdown
# 🔥 리스크 관리 & 성과 평가 API 가이드
|
|
|
|
## 개요
|
|
자동매매 시스템의 안정성과 수익성을 높이기 위한 리스크 관리 기능입니다.
|
|
|
|
## 주요 기능
|
|
|
|
### 1. Maximum Drawdown (MDD) 추적
|
|
**엔드포인트**: `GET /api/v1/risk/risk-metrics?days=30`
|
|
|
|
계좌 최고점 대비 최저점 낙폭을 측정합니다.
|
|
|
|
**응답 예시**:
|
|
```json
|
|
{
|
|
"max_drawdown": 150000,
|
|
"max_drawdown_pct": 15.5,
|
|
"current_equity": 850000,
|
|
"peak_equity": 1000000,
|
|
"trades_count": 45,
|
|
"risk_level": "주의",
|
|
"equity_curve": [...],
|
|
"drawdown_curve": [...]
|
|
}
|
|
```
|
|
|
|
**위험 레벨**:
|
|
- `안전`: MDD < 10%
|
|
- `주의`: 10% ≤ MDD < 20%
|
|
- `경고`: 20% ≤ MDD < 30% (포지션 축소 권장)
|
|
- `위험`: MDD ≥ 30% (시스템 중지 권장)
|
|
|
|
---
|
|
|
|
### 2. Sharpe Ratio 계산
|
|
**엔드포인트**: `GET /api/v1/risk/sharpe-ratio?days=30`
|
|
|
|
수익률 대비 변동성(리스크)을 측정하여 전략의 질을 평가합니다.
|
|
|
|
**응답 예시**:
|
|
```json
|
|
{
|
|
"sharpe_ratio": 1.85,
|
|
"avg_return": 2.3,
|
|
"std_return": 5.1,
|
|
"annualized_return": 579.6,
|
|
"interpretation": "Good (우수)",
|
|
"trades_count": 42
|
|
}
|
|
```
|
|
|
|
**해석**:
|
|
- `> 2.0`: Excellent (매우 우수)
|
|
- `> 1.0`: Good (우수)
|
|
- `> 0`: Fair (보통)
|
|
- `< 0`: Poor (개선 필요)
|
|
|
|
---
|
|
|
|
### 3. 일일 트레이딩 세션 조회
|
|
**엔드포인트**: `GET /api/v1/risk/session/today`
|
|
|
|
오늘의 연속 손실, 일일 손익, 거래 중지 상태를 확인합니다.
|
|
|
|
**응답 예시**:
|
|
```json
|
|
{
|
|
"session_date": "2026-02-11",
|
|
"consecutive_losses": 2,
|
|
"consecutive_wins": 0,
|
|
"daily_profit_loss": -45000,
|
|
"daily_trades_count": 5,
|
|
"is_paused": false,
|
|
"pause_reason": null,
|
|
"starting_balance": 10000000,
|
|
"ending_balance": 9955000,
|
|
"peak_balance": 10050000
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 4. 주문 전 리스크 제한 확인
|
|
**엔드포인트**: `POST /api/v1/risk/check-risk-limits`
|
|
|
|
**파라미터**:
|
|
- `order_value`: 주문 금액
|
|
- `account_balance`: 계좌 잔고
|
|
|
|
**응답 예시 (통과)**:
|
|
```json
|
|
{
|
|
"allowed": true,
|
|
"risk_level": "OK",
|
|
"warnings": [],
|
|
"position_ratio": 15.5,
|
|
"daily_loss_ratio": 1.2,
|
|
"consecutive_losses": 1
|
|
}
|
|
```
|
|
|
|
**응답 예시 (거부)**:
|
|
```json
|
|
{
|
|
"allowed": false,
|
|
"reason": "연속 3회 손실 발생",
|
|
"risk_level": "CRITICAL",
|
|
"consecutive_losses": 3
|
|
}
|
|
```
|
|
|
|
**자동 차단 조건**:
|
|
1. **연속 3회 손실**: 3연패 시 자동 중지
|
|
2. **일일 손실 3% 초과**: 계좌 대비 3% 손실 시 중지
|
|
3. **포지션 사이즈 20% 초과**: 단일 포지션이 계좌의 20% 초과 시 거부
|
|
|
|
---
|
|
|
|
### 5. 거래 결과 업데이트
|
|
**엔드포인트**: `POST /api/v1/risk/update-session`
|
|
|
|
**파라미터**:
|
|
- `trade_result`: `win` 또는 `loss`
|
|
- `profit_loss`: 거래 손익
|
|
|
|
매도 체결 후 호출하여 세션 상태를 업데이트합니다.
|
|
|
|
---
|
|
|
|
### 6. 승률 및 손익 통계
|
|
**엔드포인트**: `GET /api/v1/risk/win-rate?days=30`
|
|
|
|
**응답 예시**:
|
|
```json
|
|
{
|
|
"win_rate": 62.5,
|
|
"total_trades": 40,
|
|
"wins": 25,
|
|
"losses": 15,
|
|
"total_profit": 1250000,
|
|
"total_loss": 450000,
|
|
"net_profit": 800000,
|
|
"profit_factor": 2.78,
|
|
"avg_win": 50000,
|
|
"avg_loss": 30000,
|
|
"risk_reward_ratio": 1.67
|
|
}
|
|
```
|
|
|
|
**주요 지표**:
|
|
- **Profit Factor**: 총 이익 / 총 손실 (1.0 이상 권장, 2.0 이상 우수)
|
|
- **Risk/Reward Ratio**: 평균 승리 / 평균 손실 (1.5 이상 권장)
|
|
|
|
---
|
|
|
|
## 리스크 관리 설정
|
|
|
|
### 현재 기본값
|
|
```python
|
|
MAX_POSITION_SIZE_RATIO = 0.20 # 단일 포지션 20% 제한
|
|
MAX_DAILY_LOSS_RATIO = 0.03 # 일일 손실 3% 제한
|
|
MAX_CONSECUTIVE_LOSSES = 3 # 연속 3회 손실 제한
|
|
|
|
# 수수료 및 세금
|
|
COMMISSION_RATE = 0.00015 # 수수료 0.015%
|
|
TRADE_TAX_RATE = 0.0023 # 거래세 0.23% (매도만)
|
|
TOTAL_COST_RATE = 0.0026 # 왕복 약 0.26%
|
|
```
|
|
|
|
---
|
|
|
|
## 사용 예시
|
|
|
|
### 매수 전 체크
|
|
```python
|
|
# 주문 전 리스크 확인
|
|
response = requests.post(
|
|
"/api/v1/risk/check-risk-limits",
|
|
params={
|
|
"order_value": 2000000, # 200만원 주문
|
|
"account_balance": 10000000 # 1000만원 잔고
|
|
}
|
|
)
|
|
|
|
if response.json()["allowed"]:
|
|
# 매수 실행
|
|
execute_buy_order()
|
|
else:
|
|
# 주문 거부
|
|
logger.warning(f"Order rejected: {response.json()['reason']}")
|
|
```
|
|
|
|
### 매도 후 세션 업데이트
|
|
```python
|
|
# 매도 체결 후
|
|
sell_result = execute_sell_order()
|
|
|
|
# 손익에 따라 세션 업데이트
|
|
trade_result = "win" if sell_result["profit_loss"] > 0 else "loss"
|
|
|
|
requests.post(
|
|
"/api/v1/risk/update-session",
|
|
params={
|
|
"trade_result": trade_result,
|
|
"profit_loss": sell_result["profit_loss"]
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## 대시보드 표시 권장 사항
|
|
|
|
### 필수 표시 지표
|
|
1. **오늘의 상태**
|
|
- 연속 손실 횟수
|
|
- 일일 손익
|
|
- 거래 중지 상태
|
|
|
|
2. **리스크 메트릭**
|
|
- MDD %
|
|
- Sharpe Ratio
|
|
- 승률
|
|
|
|
3. **경고 알림**
|
|
- 연속 2회 손실: 노란색 경고
|
|
- 연속 3회 손실: 빨간색 차단
|
|
- MDD 20% 초과: 주황색 경고
|
|
- MDD 30% 초과: 빨간색 위험
|
|
|
|
---
|
|
|
|
## 주의사항
|
|
|
|
1. **백테스팅 후 실전 적용**: 새로운 전략은 반드시 백테스팅으로 검증
|
|
2. **리스크 한도 준수**: 설정된 한도를 절대 임의로 변경하지 않기
|
|
3. **정기 점검**: 매주 Sharpe Ratio와 MDD 확인
|
|
4. **감정 제어**: 시스템이 중지하면 하루 쉬기
|
|
|
|
---
|
|
|
|
## 다음 단계 (추가 개발 예정)
|
|
|
|
- [ ] 백테스팅 API
|
|
- [ ] Slack/Telegram 알림 연동
|
|
- [ ] 실시간 경고 대시보드
|
|
- [ ] 월간/분기별 성과 리포트
|
|
- [ ] ATR 기반 동적 손절 설정
|