auto-stock/docs/API_DOCS.md

Auto Stock Trading System - API 문서

Backend API

기본 정보

• Base URL: http://localhost:8000/api/v1
• 인증: Bearer Token (JWT)

엔드포인트

1. Trading Rules (트레이딩 규칙)

규칙 목록 조회

GET /api/v1/rules

Query Parameters:

• skip (int): 건너뛸 개수 (기본: 0)
• limit (int): 조회할 개수 (기본: 100)
• is_active (bool): 활성화 필터 (선택)

Response:

[
  {
    "id": 1,
    "name": "기본 매수 규칙",
    "description": "RSI 30 이하이고 거래량이 평균보다 높을 때 매수",
    "rule_type": "BUY",
    "conditions": {
      "rsi_below": 30,
      "volume_above_average": 1.5
    },
    "actions": {
      "order_type": "BUY",
      "quantity_percent": 10,
      "max_amount": 1000000
    },
    "is_active": true,
    "priority": 10,
    "created_at": "2024-11-04T00:00:00",
    "updated_at": "2024-11-04T00:00:00"
  }
]

규칙 생성

POST /api/v1/rules

Request Body:

{
  "name": "새 규칙",
  "description": "설명",
  "rule_type": "BUY",
  "conditions": {},
  "actions": {},
  "is_active": true,
  "priority": 10
}

규칙 수정

PUT /api/v1/rules/{rule_id}

규칙 삭제

DELETE /api/v1/rules/{rule_id}

규칙 활성화/비활성화

POST /api/v1/rules/{rule_id}/toggle

2. Trades (거래 이력)

거래 이력 조회

GET /api/v1/trades

Query Parameters:

• skip, limit: 페이지네이션
• stock_code (string): 종목 코드 필터
• status (string): 상태 필터 (PENDING, EXECUTED, FAILED)
• order_type (string): 주문 유형 (BUY, SELL)
• days (int): 조회 기간 (기본: 30일)

거래 통계

GET /api/v1/trades/stats/summary?days=30

Response:

{
  "period_days": 30,
  "total_trades": 150,
  "buy_trades": 75,
  "sell_trades": 75,
  "executed_trades": 140,
  "failed_trades": 10,
  "success_rate": 0.933,
  "total_amount": 50000000
}

3. Portfolio (포트폴리오)

포트폴리오 조회

GET /api/v1/portfolio

Response:

[
  {
    "id": 1,
    "stock_code": "005930",
    "stock_name": "삼성전자",
    "quantity": 10,
    "average_price": 70000,
    "current_price": 71000,
    "profit_loss": 10000,
    "profit_loss_rate": 1.43
  }
]

포트폴리오 동기화

GET /api/v1/portfolio/sync

실제 증권 계좌와 포트폴리오를 동기화합니다.

포트폴리오 요약

GET /api/v1/portfolio/summary

Response:

{
  "total_stocks": 5,
  "total_value": 10000000,
  "total_investment": 9500000,
  "total_profit_loss": 500000,
  "total_profit_loss_rate": 5.26
}

4. Market Data (시장 데이터)

주식 현재가 조회

GET /api/v1/market/price/{stock_code}

Response:

{
  "stock_code": "005930",
  "current_price": 71000,
  "change_rate": 1.5,
  "volume": 1000000,
  "high_price": 71500,
  "low_price": 70000,
  "open_price": 70500
}

차트 데이터 조회

GET /api/v1/market/chart/{stock_code}?period=D

Query Parameters:

• period (string): D (일봉), W (주봉), M (월봉)

5. MCP (Model Context Protocol)

MCP 서버 상태

GET /api/v1/mcp/status

Response:

{
  "status": "connected",
  "mcp_server_url": "http://mcp-server:8001",
  "details": {
    "status": "healthy",
    "claude_configured": true
  }
}

MCP 도구 목록

GET /api/v1/mcp/tools

MCP 도구 호출

POST /api/v1/mcp/tools/call

Request Body:

{
  "tool_name": "get_market_data",
  "parameters": {
    "stock_code": "005930",
    "period": "D"
  }
}

Claude AI 분석 요청

POST /api/v1/mcp/analyze

Request Body:

{
  "analysis_type": "RULE_VALIDATION",
  "data": {
    "rule": {},
    "market_data": {}
  }
}

Analysis Types:

• RULE_VALIDATION: 규칙 검증
• MARKET_ANALYSIS: 시장 분석
• RISK_ASSESSMENT: 리스크 평가

WebSocket

연결

const ws = new WebSocket('ws://localhost:8000/ws/{client_id}')

메시지 타입

Market Update

{
  "type": "market_update",
  "stock_code": "005930",
  "data": {
    "price": 71000,
    "change_rate": 1.5
  }
}

Trade Notification

{
  "type": "trade_notification",
  "data": {
    "order_id": "ORD001",
    "status": "EXECUTED"
  }
}

MCP Status

{
  "type": "mcp_status",
  "data": {
    "status": "connected"
  }
}

에러 응답

모든 에러는 다음 형식으로 반환됩니다:

{
  "detail": "에러 메시지"
}

상태 코드:

• 400: Bad Request
• 401: Unauthorized
• 404: Not Found
• 500: Internal Server Error
• 504: Gateway Timeout