본문으로 건너뛰기

FAQ

자주 묻는 30개 질문을 카테고리별로 정리했습니다. 검색 (Cmd+K)으로 키워드 빠른 탐색 가능.

회원 / 인증​

Q1. 회원가입이 안 됩니다.​

username은 영숫자 + 언더스코어만 (3–64자), email은 RFC 5322 형식, password는 8자 이상이어야 합니다. 이미 존재하는 username/email은 409 에러. 자세한 내용은 auth API 참조.

Q2. 로그인 시 401이 떨어집니다.​

원인 중 하나:

  • 비밀번호 오류
  • 계정 비활성화 (is_active=false — 운영자 문의)
  • AUTH_SECRET_KEY가 변경되어 토큰 무효화 (재로그인하면 해결)

Q3. JWT 토큰이 자주 만료됩니다.​

기본 access 토큰 30분 유효. /api/auth/refresh로 refresh 토큰을 사용해 새 access 발급. 환경변수 AUTH_ACCESS_TOKEN_TTL_MIN로 조정 가능.

Q4. 토큰을 잊어버렸습니다.​

비밀번호로 다시 로그인하면 새 토큰을 받습니다. 비밀번호 분실 복구 흐름은 P7+에서 추가 예정.

거래소 키​

Q5. 페이퍼 키 등록 후 401이 떨어집니다.​

  • paper_mode=true 확인
  • Alpaca: base_url을 https://paper-api.alpaca.markets로 명시
  • KIS: account_no, account_product_code 누락 여부 확인
  • API key/secret에 따옴표/공백 포함 여부 확인
  • your_api_key_here 같은 placeholder가 들어있는지 확인 (자주 발생)

Q6. 거래소 키를 변경하려면?​

기존 키 DELETE 후 새로 POST. UPDATE는 미지원 — secret 회전 시 재등록 절차.

Q7. 키 dry-run 검증이 가능한가요?​

POST /api/exchange-keys/test로 등록 전 dry-run 가능. 자세한 내용은 exchange-keys API 참조.

Q8. 키가 응답 본문에 보이나요?​

절대 노출되지 않습니다. 응답에는 api_key_masked (앞 4 + ... + 뒤 4) 형식으로만 표시됩니다.

분석​

Q9. LLM 분석이 너무 느립니다.​

mode=quick은 일반적으로 5–20초, standard는 30–90초, full은 최대 5분. 큐 모드는 비동기 — report_id만 받고 폴링하세요.

Q10. 분석 비용이 비쌉니다.​

각 보고서의 cost_usd 필드로 누적 비용을 확인. LLM_BUDGET_EXCEEDED 게이트 (사용자별 일일 예산)가 자동 적용. Settings → Notifications에서 한도 조정.

Q11. 한국 주식 시간 외 분석이 가능한가요?​

분석 자체는 24/7 가능하지만, 주문은 KRX 정규 시간 (09:00–15:30 KST)에만 통과합니다. 시간 외 주문 시 422 MARKET_CLOSED.

Q12. 분석 결과를 어떻게 검증하나요?​

/api/equity/reports/{id}/traces로 각 에이전트의 단계별 추론 + 토큰/지연을 확인. UI의 Trace 탭에서도 시각적으로 볼 수 있음.

Q13. 같은 종목을 다시 분석하려면?​

force_refresh=true 옵션 (디자인 문서 기준) 또는 새 보고서 생성. 캐시는 자동 무시됩니다.

주문​

Q14. 페이퍼 주문이 즉시 거부됩니다.​

원인:

  • RISK_RULE_VIOLATION: 거래당 1-2% 초과
  • MARKET_CLOSED: 시장 마감
  • INSUFFICIENT_FUNDS: 페이퍼 잔고 부족
  • BROKER_NOT_CONFIGURED: 자산군 키 미등록
  • FEATURE_DISABLED: FEATURE_EQUITY_PAPER=false

Q15. 백테스트와 페이퍼 결과가 다릅니다.​

자연스러운 현상 — 슬리피지/체결 지연/실시간 호가 변동 때문. 백테스트는 slippage_bps 모델, 페이퍼는 실제 호가 사용. 차이가 -5% 이상이면 전략 가정을 재검토.

Q16. Bracket 주문이 부분만 동작합니다.​

  • Crypto (CCXT): bracket 미지원, 서버측 시뮬레이션
  • Alpaca: native 지원
  • KIS: take_profit만 지원, stop_loss는 별도 주문

Q17. 주문 취소가 안 됩니다.​

asset_class query 파라미터를 누락하지 않았는지 확인. broker_order_id로만 식별이 어려워 자산군이 필수.

시장 / 자산군​

Q18. 자산군 필터가 작동하지 않습니다.​

대시보드 우측 상단 셀렉터를 확인. all / crypto / us_equity / kr_equity 중 선택. 모든 페이지에 일관 적용 (페이지 전환해도 유지).

Q19. KRW → USD 환산은 어떻게 되나요?​

data/fx.py에서 1시간 단위 환율 캐시. 통합 PnL은 모두 USD 기준 합산. by_asset_class 필드는 원래 통화 그대로.

Q20. 한국 주식 시간 외 거래 가능한가요?​

KIS 모의투자는 시간 외 매매를 일부 지원하나 quant-ai는 현재 정규 시간 (09:00–15:30 KST)만 허용. P5 이후 시간 외 옵션 검토.

리스크 / 라이브​

Q21. 일일 -5%로 자동 중단됐습니다. 어떻게 풀어요?​

다음 UTC 자정에 자동 복구. 즉시 재개가 필요한 경우 admin 토큰으로 POST /api/bot/resume 호출 (권장하지 않음). 자세한 내용은 운영 인시던트 참조.

Q22. 라이브 모드 활성화 조건이 무엇인가요?​

절대 룰: 자산군별 페이퍼 90일+50거래. /api/equity/live/status의 is_ready=true 확인 후 request_confirm → enable 2단계 토큰 인증.

Q23. 라이브 일일 거래 한도를 늘릴 수 있나요?​

LIVE_DAILY_TRADE_LIMIT 환경변수로 운영자가 조정 가능. 단, 일일 -5% 룰은 절대 우회 불가.

Q24. 페이퍼와 라이브 키를 동시에 등록 가능한가요?​

자산군당 1개 키만 등록 가능 (label로 구분 시도해도 1개만 active). 페이퍼 → 라이브 전환 시 기존 키 삭제 후 라이브 키 재등록 (P4-01).

백테스트​

Q25. 백테스트 결과를 다른 형식으로 export 가능한가요?​

UI의 Backtest → Result → Export 버튼으로 CSV/JSON 다운로드 (P5-03 추가 예정). API에서는 equity_curve + trades 배열을 직접 파싱하여 사용.

Q26. Walk-forward 백테스트가 가능한가요?​

P5-04에서 추가 예정. 현재는 단일 윈도 백테스트만 지원.

Q27. 자체 전략 추가 방법은?​

config/strategies/equity/<name>.yaml 작성 + 서버 재시작. 자세한 흐름은 튜토리얼: 자체 전략 추가 참조.

멀티유저 / 보안​

Q28. 멀티유저 데이터 격리를 어떻게 검증하나요?​

다른 user 토큰으로 본인의 report_id에 접근 시 일관되게 404 응답이어야 합니다. 테스트:

# user-A의 보고서 ID로 user-B 토큰 접근
curl -H "Authorization: Bearer $JWT_USER_B" \
  http://localhost:8000/api/equity/reports/<user_a_report_id>
# → 404

Q29. 시크릿을 회전했더니 키가 사라졌습니다.​

ENCRYPTION_SALT 변경 시 기존 거래소 키는 복호화 불가 (mask는 ****로 표시). 사용자가 키를 재등록해야 합니다. AUTH_SECRET_KEY 변경 시 모든 JWT 무효화 — 재로그인.

알림​

Q30. Telegram 알림이 안 옵니다.​

체크리스트:

  1. Settings → Notifications에서 bot token + chat_id 등록 확인
  2. Telegram bot에 /start 메시지 1회 발송했는지 확인 (chat_id 활성화)
  3. docker compose logs api | grep telegram 로그 확인
  4. 방화벽이 api.telegram.org로 outbound 허용하는지 확인
  5. Settings → Notifications → Test alert 버튼으로 강제 발송 테스트

자세한 내용은 모니터링: Telegram 알림 참조.