auto-stock/docs/RISK_MANAGEMENT_API.md

🔥 리스크 관리 & 성과 평가 API 가이드

개요

자동매매 시스템의 안정성과 수익성을 높이기 위한 리스크 관리 기능입니다.

주요 기능

1. Maximum Drawdown (MDD) 추적

엔드포인트: GET /api/v1/risk/risk-metrics?days=30

계좌 최고점 대비 최저점 낙폭을 측정합니다.

응답 예시:

{
  "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

수익률 대비 변동성(리스크)을 측정하여 전략의 질을 평가합니다.

응답 예시:

{
  "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

오늘의 연속 손실, 일일 손익, 거래 중지 상태를 확인합니다.

응답 예시:

{
  "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: 계좌 잔고

응답 예시 (통과):

{
  "allowed": true,
  "risk_level": "OK",
  "warnings": [],
  "position_ratio": 15.5,
  "daily_loss_ratio": 1.2,
  "consecutive_losses": 1
}

응답 예시 (거부):

{
  "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

응답 예시:

{
  "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 이상 권장)

---

리스크 관리 설정

현재 기본값

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%

---

사용 예시

매수 전 체크

# 주문 전 리스크 확인
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']}")

매도 후 세션 업데이트

# 매도 체결 후
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 기반 동적 손절 설정