본문으로 건너뛰기

API 레퍼런스

quant-ai는 FastAPI 기반의 REST + WebSocket API를 제공합니다. 모든 응답은 Pydantic v2 모델로 정의되며, FastAPI 자동 스웨거 문서는 http://localhost:8000/docs에서 확인할 수 있습니다.

베이스 URL​

환경베이스 URL
로컬http://localhost:8000
Azure VMhttp://20.196.217.226:8000 (배포 IP)
WebSocketws://<host>/ws/...

인증​

JWT Bearer 토큰 기반 인증입니다. 모든 라우트(/api/auth/*, /health, /metrics, /docs 제외)는 인증이 필요합니다.

헤더 형식​

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

토큰 발급​

POST /api/auth/login으로 access + refresh 토큰을 발급받습니다. 자세한 내용은 auth 참조.

WebSocket 인증​

WebSocket은 헤더 대신 ?token=<JWT> query 파라미터로 인증합니다.

const ws = new WebSocket(`ws://localhost:8000/ws/equity/orders?token=${jwt}`);

멀티유저 격리​

모든 라우트는 WHERE user_id = current_user.id 필터링을 강제 적용합니다. 다른 user의 리소스에 접근 시도는 일관되게 404 Not Found를 반환합니다 (403이 아닌 404로 응답하여 리소스 존재 여부 노출 방지).

에러 envelope​

표준 에러 응답 형식:

{
  "detail": {
    "error_code": "RISK_RULE_VIOLATION",
    "message": "Order exceeds 2% per-trade risk limit (calculated: 3.4%)",
    "details": {
      "max_pct": 0.02,
      "calculated_pct": 0.034
    }
  }
}

레거시 라우트(/api/auth/* 등)는 평탄한 {"detail": "message"} 형식을 사용합니다.

표준 에러 코드​

코드HTTP설명
INVALID_SYMBOL422심볼이 자산군 매핑에 등록되지 않음
INVALID_ASSET_CLASS422crypto/us_equity/kr_equity 외 값
INVALID_QUANTITY422qty ≤ 0
INVALID_ORDER_TYPE422알 수 없는 order_type
MARKET_CLOSED422시장 마감 시간
DUPLICATE_CLIENT_ORDER_ID409중복 client_order_id
RISK_RULE_VIOLATION4221-2% / -5% 룰 위반
INSUFFICIENT_FUNDS422잔고 부족
LLM_BUDGET_EXCEEDED402사용자 일일 LLM 예산 초과
RATE_LIMIT_EXCEEDED429일반 rate limit
RATE_LIMIT_LIVE_DAILY429LIVE_DAILY_TRADE_LIMIT 초과
BROKER_UNAVAILABLE502브로커 5xx / 네트워크 오류
BROKER_NOT_CONFIGURED403사용자 브로커 키 미등록
BROKER_REJECTED422브로커가 명시적으로 거부
REPORT_NOT_FOUND404보고서 없음 (또는 다른 user 소유)
ORDER_NOT_FOUND404주문 없음
LIVE_NOT_ENABLED403라이브 게이트 미통과
FEATURE_DISABLED503feature flag OFF
FORBIDDEN403권한 부족

응답 일반 규칙​

  • 시간: ISO 8601 + UTC (2026-04-26T13:55:01.123Z)
  • 가격: 소수 (예: 188.20), 통화는 별도 필드 (currency: "USD")
  • UUID: 문자열 (예: "0c3a5b4f-...")
  • 페이지네이션: page (1-based) + size + total 또는 next_cursor

Rate limit​

엔드포인트한도
POST /api/equity/analyze사용자별 분당 5회
POST /api/equity/orders사용자별 분당 30회
POST /api/auth/loginIP당 분당 10회

429 응답 시 Retry-After 헤더가 포함되지 않을 수 있으므로 12초(분당 5회의 평균 간격) 또는 6초(30회) 대기 후 재시도하세요.

Feature flag​

변수기본값영향
FEATURE_LLM_ANALYSIStrue/api/equity/analyze
FEATURE_EQUITY_ANALYSIStrue/api/equity/analyze (alias)
FEATURE_EQUITY_PAPERfalse`/api/equity/orders
FEATURE_EQUITY_LIVEfalse/api/equity/live/*, live_mode=true 주문

FEATURE_DISABLED 코드의 503 응답은 위 플래그 OFF가 원인입니다.

라우트 카테고리​

  • auth — 회원가입/로그인/토큰 관리
  • equity-analyze — 멀티 에이전트 분석 + 보고서 + trace
  • equity-orders — 페이퍼/라이브 주문 + 포지션 + 계좌
  • equity-backtest — 주식 전략 백테스트
  • equity-live — 라이브 모드 게이팅 (request_confirm/enable/disable/status)
  • exchange-keys — 거래소/브로커 API 키 관리
  • websockets — /ws/live, /ws/equity/orders

OpenAPI 스펙​

FastAPI 자동 생성 스펙은 다음 경로에서 받을 수 있습니다.

  • Swagger UI: http://localhost:8000/docs
  • Redoc: http://localhost:8000/redoc
  • OpenAPI JSON: http://localhost:8000/openapi.json