수정본
This commit is contained in:
308
docs/API_DOCS.md
Normal file
308
docs/API_DOCS.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# Auto Stock Trading System - API 문서
|
||||
|
||||
## Backend API
|
||||
|
||||
### 기본 정보
|
||||
|
||||
- **Base URL**: `http://localhost:8000/api/v1`
|
||||
- **인증**: Bearer Token (JWT)
|
||||
|
||||
## 엔드포인트
|
||||
|
||||
### 1. Trading Rules (트레이딩 규칙)
|
||||
|
||||
#### 규칙 목록 조회
|
||||
```http
|
||||
GET /api/v1/rules
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `skip` (int): 건너뛸 개수 (기본: 0)
|
||||
- `limit` (int): 조회할 개수 (기본: 100)
|
||||
- `is_active` (bool): 활성화 필터 (선택)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 규칙 생성
|
||||
```http
|
||||
POST /api/v1/rules
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "새 규칙",
|
||||
"description": "설명",
|
||||
"rule_type": "BUY",
|
||||
"conditions": {},
|
||||
"actions": {},
|
||||
"is_active": true,
|
||||
"priority": 10
|
||||
}
|
||||
```
|
||||
|
||||
#### 규칙 수정
|
||||
```http
|
||||
PUT /api/v1/rules/{rule_id}
|
||||
```
|
||||
|
||||
#### 규칙 삭제
|
||||
```http
|
||||
DELETE /api/v1/rules/{rule_id}
|
||||
```
|
||||
|
||||
#### 규칙 활성화/비활성화
|
||||
```http
|
||||
POST /api/v1/rules/{rule_id}/toggle
|
||||
```
|
||||
|
||||
### 2. Trades (거래 이력)
|
||||
|
||||
#### 거래 이력 조회
|
||||
```http
|
||||
GET /api/v1/trades
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `skip`, `limit`: 페이지네이션
|
||||
- `stock_code` (string): 종목 코드 필터
|
||||
- `status` (string): 상태 필터 (PENDING, EXECUTED, FAILED)
|
||||
- `order_type` (string): 주문 유형 (BUY, SELL)
|
||||
- `days` (int): 조회 기간 (기본: 30일)
|
||||
|
||||
#### 거래 통계
|
||||
```http
|
||||
GET /api/v1/trades/stats/summary?days=30
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"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 (포트폴리오)
|
||||
|
||||
#### 포트폴리오 조회
|
||||
```http
|
||||
GET /api/v1/portfolio
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"stock_code": "005930",
|
||||
"stock_name": "삼성전자",
|
||||
"quantity": 10,
|
||||
"average_price": 70000,
|
||||
"current_price": 71000,
|
||||
"profit_loss": 10000,
|
||||
"profit_loss_rate": 1.43
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 포트폴리오 동기화
|
||||
```http
|
||||
GET /api/v1/portfolio/sync
|
||||
```
|
||||
|
||||
실제 증권 계좌와 포트폴리오를 동기화합니다.
|
||||
|
||||
#### 포트폴리오 요약
|
||||
```http
|
||||
GET /api/v1/portfolio/summary
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total_stocks": 5,
|
||||
"total_value": 10000000,
|
||||
"total_investment": 9500000,
|
||||
"total_profit_loss": 500000,
|
||||
"total_profit_loss_rate": 5.26
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Market Data (시장 데이터)
|
||||
|
||||
#### 주식 현재가 조회
|
||||
```http
|
||||
GET /api/v1/market/price/{stock_code}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"stock_code": "005930",
|
||||
"current_price": 71000,
|
||||
"change_rate": 1.5,
|
||||
"volume": 1000000,
|
||||
"high_price": 71500,
|
||||
"low_price": 70000,
|
||||
"open_price": 70500
|
||||
}
|
||||
```
|
||||
|
||||
#### 차트 데이터 조회
|
||||
```http
|
||||
GET /api/v1/market/chart/{stock_code}?period=D
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `period` (string): D (일봉), W (주봉), M (월봉)
|
||||
|
||||
### 5. MCP (Model Context Protocol)
|
||||
|
||||
#### MCP 서버 상태
|
||||
```http
|
||||
GET /api/v1/mcp/status
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "connected",
|
||||
"mcp_server_url": "http://mcp-server:8001",
|
||||
"details": {
|
||||
"status": "healthy",
|
||||
"claude_configured": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### MCP 도구 목록
|
||||
```http
|
||||
GET /api/v1/mcp/tools
|
||||
```
|
||||
|
||||
#### MCP 도구 호출
|
||||
```http
|
||||
POST /api/v1/mcp/tools/call
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"tool_name": "get_market_data",
|
||||
"parameters": {
|
||||
"stock_code": "005930",
|
||||
"period": "D"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Claude AI 분석 요청
|
||||
```http
|
||||
POST /api/v1/mcp/analyze
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"analysis_type": "RULE_VALIDATION",
|
||||
"data": {
|
||||
"rule": {},
|
||||
"market_data": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Analysis Types:**
|
||||
- `RULE_VALIDATION`: 규칙 검증
|
||||
- `MARKET_ANALYSIS`: 시장 분석
|
||||
- `RISK_ASSESSMENT`: 리스크 평가
|
||||
|
||||
## WebSocket
|
||||
|
||||
### 연결
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:8000/ws/{client_id}')
|
||||
```
|
||||
|
||||
### 메시지 타입
|
||||
|
||||
#### Market Update
|
||||
```json
|
||||
{
|
||||
"type": "market_update",
|
||||
"stock_code": "005930",
|
||||
"data": {
|
||||
"price": 71000,
|
||||
"change_rate": 1.5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Trade Notification
|
||||
```json
|
||||
{
|
||||
"type": "trade_notification",
|
||||
"data": {
|
||||
"order_id": "ORD001",
|
||||
"status": "EXECUTED"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### MCP Status
|
||||
```json
|
||||
{
|
||||
"type": "mcp_status",
|
||||
"data": {
|
||||
"status": "connected"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 에러 응답
|
||||
|
||||
모든 에러는 다음 형식으로 반환됩니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "에러 메시지"
|
||||
}
|
||||
```
|
||||
|
||||
**상태 코드:**
|
||||
- `400`: Bad Request
|
||||
- `401`: Unauthorized
|
||||
- `404`: Not Found
|
||||
- `500`: Internal Server Error
|
||||
- `504`: Gateway Timeout
|
||||
Reference in New Issue
Block a user