executor/API_USAGE_GUIDE.md

BAA 전략 API 사용 가이드

시작하기

1. 서버 실행

# 개발 서버 실행
python manage.py runserver

# 서버가 http://localhost:8000 에서 실행됩니다

2. 준비된 스크립트 사용

세 가지 편리한 스크립트가 제공됩니다:

A. 전체 예제 실행 (baa_api_examples.sh)

모든 주요 기능을 순차적으로 테스트합니다.

./baa_api_examples.sh

실행 내용:

1. 사용 가능한 전략 목록 조회
2. BAA-G12 시뮬레이션 모드 실행
3. BAA-G4 실제 데이터 모드 (현재 날짜)
4. BAA-G12 특정 날짜 기준 (2024-01-31)

B. 빠른 테스트 (quick_baa_test.sh)

단일 포트폴리오를 빠르게 생성하고 요약 정보를 표시합니다.

# 기본 실행 (BAA-G4, $50,000, 현재 날짜)
./quick_baa_test.sh

# 전략 변형 지정
./quick_baa_test.sh BAA-G12

# 전략 + 초기 자본 지정
./quick_baa_test.sh BAA-G4 100000

# 전략 + 초기 자본 + 특정 날짜
./quick_baa_test.sh BAA-G12 75000 2024-01-31

출력 예시:

====== 포트폴리오 요약 ======
기준일: 2025-10-04
모드: offensive
카나리아 bad 개수: 0
총 투자액: $49947.08
잔여 현금: $52.92

====== 포트폴리오 구성 ======
VEA: 818주 @ $61.06 = $49947.08

====== 카나리아 상태 ======
SPY: 모멘텀=8.55%, bad=false
VWO: 모멘텀=10.15%, bad=false
VEA: 모멘텀=8.63%, bad=false
BND: 모멘텀=1.32%, bad=false

C. 개별 curl 명령어 참조 (BAA_CURL_EXAMPLES.md)

다양한 curl 명령어 예제와 응답 샘플을 포함한 상세 가이드입니다.

---

API 엔드포인트

1. 전략 구현체 목록 조회

요청:

GET /api/strategies/implementations/

응답:

{
  "available_implementations": {
    "BoldAssetAllocation": {
      "name": "BoldAssetAllocation",
      "description": "상대 모멘텀과 절대 모멘텀을 결합한 공격적 전술적 자산배분 전략",
      "versions": [...]
    }
  }
}

2. 전략 실행

요청:

POST /api/strategies/execute/
Content-Type: application/json

{
  "strategy_name": "BoldAssetAllocation",
  "version": "1.0.0",
  "parameters": {
    "initial_capital": 50000,
    "variant": "BAA-G4",
    "use_real_data": true,
    "as_of_date": null
  }
}

응답:

{
  "execution_id": 123,
  "status": "pending",
  "message": "Strategy execution started"
}

3. 전략 백테스트

과거 데이터를 기반으로 월별 리밸런싱을 반복 수행하며 포트폴리오 성과를 추적합니다.

요청:

POST /api/strategies/backtest/
Content-Type: application/json

{
  "strategy_name": "BoldAssetAllocation",
  "parameters": {
    "backtest_start_date": "2020-01-01",
    "backtest_end_date": "2024-12-31",
    "initial_capital": 100000,
    "variant": "BAA-G12",
    "transaction_cost": 0.001
  }
}

응답:

{
  "execution_id": 456,
  "status": "pending",
  "message": "Backtest execution started"
}

실행은 비동기로 처리됩니다. 아래 실행 결과 조회 엔드포인트로 폴링하세요.

백테스트 결과 (폴링 응답):

{
  "execution_id": 456,
  "status": "completed",
  "result": {
    "strategy": "BoldAssetAllocation",
    "variant": "BAA-G12",
    "backtest_start_date": "2020-01-01",
    "backtest_end_date": "2024-12-31",
    "initial_capital": 100000,
    "final_capital": 138742.31,
    "metrics": {
      "cagr": 6.78,
      "total_return": 38.74,
      "annual_volatility": 7.52,
      "max_drawdown": 8.12,
      "sharpe_ratio": 0.90,
      "sortino_ratio": 1.42,
      "calmar_ratio": 0.83,
      "win_rate": 65.0,
      "best_month": 4.23,
      "worst_month": -3.87
    },
    "daily_equity_curve": [
      {"date": "2020-01-02", "value": 100050.0},
      ...
    ],
    "monthly_returns": [
      {"date": "2020-01-31", "return": 0.0023},
      ...
    ],
    "allocation_history": [
      {
        "date": "2020-01-31",
        "mode": "offensive",
        "weights": {"SPY": 0.1667, "QQQ": 0.1667, ...},
        "turnover": 1.0,
        "cost": 100.0
      },
      ...
    ],
    "drawdown_series": [
      {"date": "2020-01-02", "drawdown": -0.05},
      ...
    ]
  }
}

백테스트 파라미터:

파라미터	필수	기본값	설명
backtest_start_date	✓	-	백테스트 시작일 (YYYY-MM-DD)
backtest_end_date	✓	-	백테스트 종료일 (YYYY-MM-DD)
initial_capital	✗	100000	초기 자본 (달러)
variant	✗	"BAA-G12"	전략 변형
transaction_cost	✗	0.001	거래비용 비율 (0.1%)

성과 지표 설명:

지표	설명
cagr	연평균 복리 수익률 (%)
total_return	총 수익률 (%)
annual_volatility	연율화 변동성 (%)
max_drawdown	최대 낙폭 (%)
sharpe_ratio	샤프 비율 (무위험 수익률 0% 가정)
sortino_ratio	소르티노 비율
calmar_ratio	칼마 비율 (CAGR / MDD)
win_rate	월간 승률 (%)
best_month	최고 월 수익률 (%)
worst_month	최저 월 수익률 (%)

4. 실행 결과 조회

요청:

GET /api/executions/{execution_id}/

응답 (완료 시):

{
  "execution_id": 123,
  "strategy": "BoldAssetAllocation",
  "version": "1.0.0",
  "status": "completed",
  "started_at": "2025-10-04T10:30:00Z",
  "completed_at": "2025-10-04T10:30:10Z",
  "result": {
    "mode": "offensive",
    "portfolio": [...],
    "canary_status": {...}
  }
}

---

주요 파라미터

파라미터	필수	기본값	설명
initial_capital	✓	100000	초기 자본 (달러)
variant	✓	"BAA-G12"	전략 변형 (BAA-G12, BAA-G4, BAA-G12/T3, BAA-G4/T2, BAA-SPY)
use_real_data	✓	false	실제 데이터 사용 여부
as_of_date	✗	null	기준일 (YYYY-MM-DD 형식, null이면 현재)
offensive_top	✗	전략별	공격 유니버스에서 선택할 자산 수
defensive_top	✗	3	방어 유니버스에서 선택할 자산 수
breadth_param	✗	1	카나리아 임계값

---

전략 변형별 특징

BAA-G12 (Balanced)

• 추천 대상: 중위험 선호, 분산 투자
• 자산 수: 12개 (주식 7 + 대체자산 3 + 채권 2)
• 선택: Top 6
• 기대 CAGR: ~14.6%
• 기대 MaxDD: ~8.7%

./quick_baa_test.sh BAA-G12 100000

BAA-G4 (Aggressive)

• 추천 대상: 고위험 선호, 집중 투자
• 자산 수: 4개 (QQQ, VWO, VEA, BND)
• 선택: Top 1
• 기대 CAGR: ~21.0%
• 기대 MaxDD: ~14.6%

./quick_baa_test.sh BAA-G4 100000

BAA-G12/T3

• 추천 대상: BAA-G12와 G4의 중간
• 자산 수: 12개
• 선택: Top 3
• 기대 CAGR: ~16.4%
• 기대 MaxDD: ~11.4%

./quick_baa_test.sh BAA-G12/T3 100000

BAA-G4/T2

• 추천 대상: 적당한 공격성
• 자산 수: 4개
• 선택: Top 2
• 기대 CAGR: ~17.7%
• 기대 MaxDD: ~12.7%

./quick_baa_test.sh BAA-G4/T2 100000

BAA-SPY

• 추천 대상: 단순함 선호, SPY 기반
• 자산 수: 1개 (SPY)
• 선택: SPY만 사용
• 기대 CAGR: ~11.4%
• 기대 MaxDD: ~16.2%

./quick_baa_test.sh BAA-SPY 100000

---

실행 모드

시뮬레이션 모드 (use_real_data: false)

• 목적: 백테스트 결과 확인
• 데이터: 1970-2022년 통계 기반
• 실행 시간: ~2초
• 결과: CAGR, Sharpe Ratio, Max DD 등 성과 지표

curl -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "variant": "BAA-G12",
      "use_real_data": false
    }
  }'

백테스트 모드 (/api/strategies/backtest/)

• 목적: 과거 데이터 기반 전략 성과 검증
• 데이터: yfinance API를 통한 과거 가격 (전체 기간 일괄 다운로드)
• 실행 시간: ~30초-2분 (기간 및 자산 수에 따라)
• 결과: 일별 equity curve, 월별 수익률, 배분 이력, 성과 지표 (CAGR, MDD, Sharpe 등)
• 리밸런싱: 월말 영업일 기준

curl -X POST http://localhost:8000/api/strategies/backtest/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "backtest_start_date": "2020-01-01",
      "backtest_end_date": "2024-12-31",
      "initial_capital": 100000,
      "variant": "BAA-G12"
    }
  }'

실제 데이터 모드 (use_real_data: true)

• 목적: 실제 포트폴리오 제안
• 데이터: yfinance API를 통한 실시간 가격
• 실행 시간: ~5-15초 (데이터 다운로드 포함)
• 결과: 티커별 매수 수량, 현재가, 배분액

curl -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "variant": "BAA-G4",
      "initial_capital": 50000,
      "use_real_data": true
    }
  }'

---

포트폴리오 해석

공격 모드 (Offensive)

카나리아 자산이 모두 양호할 때 활성화됩니다.

특징:

• 주식 및 성장 자산에 투자
• 높은 수익 잠재력
• 선택된 자산에 동일 가중 배분

예시:

{
  "mode": "offensive",
  "canary_bad_count": 0,
  "portfolio": [
    {"ticker": "VEA", "weight": 100.0, "shares": 818}
  ]
}

방어 모드 (Defensive)

카나리아 자산 중 1개 이상이 음수 모멘텀일 때 활성화됩니다.

특징:

• 채권 및 안전 자산으로 전환
• 크래시 보호
• Top 3 방어 자산 선택

예시:

{
  "mode": "defensive",
  "canary_bad_count": 1,
  "portfolio": [
    {"ticker": "DBC", "weight": 33.33, "shares": 1555},
    {"ticker": "TLT", "weight": 33.33, "shares": 374},
    {"ticker": "LQD", "weight": 33.33, "shares": 327}
  ]
}

---

워크플로우 예시

월간 리밸런싱 워크플로우

#!/bin/bash
# monthly_rebalance.sh

# 1. 현재 포트폴리오 생성
EXEC_ID=$(curl -s -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "initial_capital": 100000,
      "variant": "BAA-G12",
      "use_real_data": true
    }
  }' | jq -r '.execution_id')

# 2. 실행 완료 대기
sleep 10

# 3. 결과 조회 및 저장
DATE=$(date +%Y%m%d)
curl -s http://localhost:8000/api/executions/${EXEC_ID}/ \
  | jq '.result' > portfolio_${DATE}.json

# 4. 매수 주문 생성 (예시)
jq -r '.portfolio[] | "BUY \(.shares) \(.ticker) @ \(.current_price)"' \
  portfolio_${DATE}.json > orders_${DATE}.txt

echo "Portfolio saved to portfolio_${DATE}.json"
echo "Orders saved to orders_${DATE}.txt"

---

트러블슈팅

1. "execution_id": null

원인: 전략 이름 또는 파라미터 오류

해결:

# 사용 가능한 전략 확인
curl http://localhost:8000/api/strategies/implementations/

2. "status": "failed"

원인: 파라미터 검증 실패 또는 데이터 다운로드 오류

확인:

curl http://localhost:8000/api/executions/{execution_id}/ | jq '.error_message'

3. 데이터 다운로드 실패

원인: 네트워크 또는 yfinance API 문제

해결:

• 인터넷 연결 확인
• 잠시 후 재시도
• 다른 날짜로 시도

4. 서버 응답 없음

확인:

# 서버 상태 확인
curl http://localhost:8000/api/strategies/implementations/

# Django 서버 로그 확인
python manage.py runserver  # 콘솔 출력 확인

---

성능 최적화

1. 병렬 실행

여러 전략을 동시에 실행할 수 있습니다:

# 동시 실행
curl -X POST http://localhost:8000/api/strategies/execute/ \
  -d '{"strategy_name":"BoldAssetAllocation","parameters":{"variant":"BAA-G12","use_real_data":true}}' &

curl -X POST http://localhost:8000/api/strategies/execute/ \
  -d '{"strategy_name":"BoldAssetAllocation","parameters":{"variant":"BAA-G4","use_real_data":true}}' &

wait

2. 캐싱 (향후 구현 예정)

동일한 날짜의 반복 요청은 캐시된 데이터를 사용할 수 있습니다.

---

보안 고려사항

프로덕션 환경

• @csrf_exempt 제거 및 CSRF 토큰 사용
• API 키 인증 추가
• HTTPS 사용
• Rate limiting 적용

---

다음 단계

1. 자동화: cron을 사용한 월간 자동 리밸런싱
2. 알림: 이메일/슬랙 알림 설정
3. 대시보드: 웹 UI 추가
4. 추가 전략 백테스트: 다른 전략에도 BacktestMixin 구현하여 백테스트 지원

---

지원

문제가 발생하면 다음을 확인하세요:

• Django 서버 로그
• BAA_CURL_EXAMPLES.md 예제
• BAA_STRATEGY_README.md 전략 설명