Equity Backtest — /api/equity/backtest

주식 자산군 (us_equity/kr_equity) 단일 종목 백테스트를 실행하고 결과를 영속화합니다.

공통

• 베이스 경로: /api/equity/backtest
• Feature flag: FEATURE_EQUITY_PAPER ON
• 멀티유저 격리: BacktestResult.user_id FK + WHERE user_id = current_user.id
• 백그라운드 실행 (요청 본문 검증 후 즉시 비동기 실행, 응답에 결과 포함)

---

POST /api/equity/backtest

백테스트 실행 + 영속화 + 결과 반환.

요청 (EquityBacktestRequest)

필드	타입	필수	기본	설명
symbol	string (1–32)	Y	—	자산군 native 심볼
asset_class	us_equity|kr_equity	Y	—	crypto는 /api/backtest/run 사용
strategy_name	string (1–64)	Y	—	등록된 전략 이름 (소문자 정규화됨)
strategy_params	dict	N	null	전략 init 인자 override
start_date	date (YYYY-MM-DD)	Y	—	시작 (포함)
end_date	date (YYYY-MM-DD)	Y	—	종료 (포함, start보다 이후)
initial_capital	float (>0)	N	10000.0	시작 자본
profile_name	string (≤64)	N	자산군 default	alpaca_zero / kis_default 등
timeframe	1d	N	1d	현재 1d만 지원

응답 200 (EquityBacktestResponse)

{
  "result_id": "f1a2b3...",
  "asset_class": "us_equity",
  "currency": "USD",
  "profile_name": "alpaca_zero",
  "strategy_name": "ma_golden_cross",
  "symbol": "AAPL",
  "start_date": "2023-01-01",
  "end_date": "2024-12-31",
  "initial_capital": 10000.0,
  "final_capital": 11842.50,
  "total_return_pct": 0.1843,
  "annual_return": 0.0892,
  "sharpe_ratio": 1.21,
  "max_drawdown_pct": -0.0834,
  "win_rate": 0.58,
  "profit_factor": 1.42,
  "total_trades": 24,
  "buy_hold_return_pct": 0.2102,
  "equity_curve": [
    {"date": "2023-01-03", "equity": 10000.0},
    {"date": "2023-01-04", "equity": 10112.40}
  ],
  "trades": [
    {
      "timestamp": "2023-02-14T15:30:00Z",
      "symbol": "AAPL",
      "side": "buy",
      "price": 152.30,
      "amount": 50.0,
      "fee": 0.0
    }
  ]
}

equity_curve는 최대 4,000 포인트, trades는 최대 1,000건으로 트림됩니다.

에러

• 422 — INVALID_ASSET_CLASS, 미등록 strategy_name, end_date ≤ start_date
• 503 — FEATURE_DISABLED

cURL

curl -X POST http://localhost:8000/api/equity/backtest \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "asset_class": "us_equity",
    "strategy_name": "ma_golden_cross",
    "start_date": "2023-01-01",
    "end_date": "2024-12-31",
    "initial_capital": 10000.0,
    "profile_name": "alpaca_zero"
  }'

TypeScript

const result = await api.post<EquityBacktestResponse>('/api/equity/backtest', {
  symbol: 'AAPL',
  asset_class: 'us_equity',
  strategy_name: 'ma_golden_cross',
  start_date: '2023-01-01',
  end_date: '2024-12-31',
  initial_capital: 10000.0,
});

---

GET /api/equity/backtest

호출자의 백테스트 목록 (요약).

Query 파라미터

파라미터	기본	설명
asset_class	—	us_equity / kr_equity 필터
symbol	—	정확 일치
strategy	—	전략명 필터
page	1	1-based
size	20	1–100

응답 200 (EquityBacktestListResponse)

{
  "items": [
    {
      "result_id": "f1a2b3...",
      "asset_class": "us_equity",
      "currency": "USD",
      "profile_name": "alpaca_zero",
      "strategy_name": "ma_golden_cross",
      "symbol": "AAPL",
      "start_date": "2023-01-01",
      "end_date": "2024-12-31",
      "total_return_pct": 0.1843,
      "sharpe_ratio": 1.21,
      "max_drawdown_pct": -0.0834,
      "win_rate": 0.58,
      "total_trades": 24,
      "created_at": "2026-04-26T10:00:00Z"
    }
  ],
  "total": 7,
  "page": 1,
  "size": 20
}

요약에는 equity_curve / trades 배열이 포함되지 않습니다 (DB JSON 컬럼 비대화 방지).

cURL

curl -H "Authorization: Bearer $JWT" \
  "http://localhost:8000/api/equity/backtest?asset_class=us_equity&page=1"

---

GET /api/equity/backtest/{result_id}

단일 백테스트 상세 (전체 equity_curve + trades 포함).

응답 200 (EquityBacktestResponse)

POST 응답과 동일.

에러

• 404 — 다른 user 결과 또는 미존재

cURL

curl -H "Authorization: Bearer $JWT" \
  http://localhost:8000/api/equity/backtest/f1a2b3...

---

멀티유저 격리

• BacktestResult.user_id FK
• 모든 GET 라우트에 WHERE user_id = current_user.id
• 다른 user의 result_id 접근 시 404

비고

• crypto 자산군 백테스트는 기존 /api/backtest/run 라우트 사용 (호환성 유지)
• profile_name 미지정 시 자산군별 default profile 자동 적용
• 백테스트 비용: API 호출은 무료 (LLM 미사용). 단 OHLCV 데이터 적재가 사전에 필요
• 등록된 전략 목록은 /api/strategy/list에서 조회

Walk-forward 백테스트

walk-forward 백테스트 (롤링 윈도 학습/검증)는 P5-04에서 추가될 예정입니다. 현재는 단일 윈도 백테스트만 지원.