174 lines
4.5 KiB
Markdown
174 lines
4.5 KiB
Markdown
# Trading Module
|
|
|
|
한국투자증권 API를 활용한 주식 매매 실행 모듈
|
|
|
|
## 모듈 구조
|
|
|
|
```
|
|
trading/
|
|
├── __init__.py # 모듈 내보내기
|
|
├── kis_client.py # KIS REST API 클라이언트 (토큰 관리)
|
|
├── order_manager.py # 주문 실행·취소·조회
|
|
├── market_data.py # 시세·차트 조회 (Redis 캐시)
|
|
└── README.md # 문서
|
|
```
|
|
|
|
## 사용 방법
|
|
|
|
### 1. KIS API 클라이언트
|
|
|
|
```python
|
|
from app.trading import kis_client
|
|
|
|
# 토큰 자동 관리 (파일 캐싱)
|
|
token = await kis_client.get_access_token()
|
|
|
|
# REST API 요청 (재시도 + 쓰로틀링 자동)
|
|
result, headers = await kis_client.request(
|
|
"GET",
|
|
"/uapi/domestic-stock/v1/quotations/inquire-price",
|
|
"FHKST01010100",
|
|
params={"FID_INPUT_ISCD": "005930"}
|
|
)
|
|
```
|
|
|
|
### 2. 주문 관리
|
|
|
|
```python
|
|
from app.trading import order_manager
|
|
|
|
# 매수 주문
|
|
result = await order_manager.place_order(
|
|
stock_code="005930",
|
|
order_type="BUY",
|
|
quantity=10,
|
|
price=75000 # None이면 시장가
|
|
)
|
|
|
|
# 주문 취소
|
|
await order_manager.cancel_order(
|
|
order_id="0000123456",
|
|
quantity=10
|
|
)
|
|
|
|
# 계좌 잔고 조회
|
|
balance = await order_manager.get_balance()
|
|
print(balance['output2']) # 보유 종목 목록
|
|
```
|
|
|
|
### 3. 시세 데이터
|
|
|
|
```python
|
|
from app.trading import market_data_provider
|
|
|
|
# 현재가 조회
|
|
price = await market_data_provider.get_current_price("005930")
|
|
print(price['output']['stck_prpr']) # 현재가
|
|
|
|
# 일봉 차트 (Redis 캐시 5분)
|
|
chart = await market_data_provider.get_daily_chart(
|
|
stock_code="005930",
|
|
period="D", # D: 일봉, W: 주봉, M: 월봉
|
|
limit=100
|
|
)
|
|
for candle in chart['output2']:
|
|
print(candle['stck_clpr']) # 종가
|
|
|
|
# 분봉 차트 (Redis 캐시 1분)
|
|
minute_chart = await market_data_provider.get_minute_chart(
|
|
stock_code="005930",
|
|
ref_time="153000", # 15:30:00 기준
|
|
include_past=True
|
|
)
|
|
|
|
# 호가 조회
|
|
orderbook = await market_data_provider.get_orderbook("005930")
|
|
print(orderbook['output1']['askp1']) # 매도 1호가
|
|
print(orderbook['output1']['bidp1']) # 매수 1호가
|
|
```
|
|
|
|
## 기존 코드 호환성
|
|
|
|
기존 `app.services.korea_investment_api` 사용 코드는 **수정 없이 동작**합니다:
|
|
|
|
```python
|
|
# 기존 방식 (DEPRECATED, 하지만 여전히 동작)
|
|
from app.services.korea_investment_api import korea_investment_api
|
|
|
|
result = await korea_investment_api.get_current_price("005930")
|
|
await korea_investment_api.place_order("005930", "BUY", 10, 75000)
|
|
|
|
# 새 방식 (권장)
|
|
from app.trading import market_data_provider, order_manager
|
|
|
|
result = await market_data_provider.get_current_price("005930")
|
|
await order_manager.place_order("005930", "BUY", 10, 75000)
|
|
```
|
|
|
|
→ `app.services.korea_investment_api_adapter.py`가 내부적으로 새 모듈로 위임하므로 기존 코드 수정 불필요
|
|
|
|
## 주요 기능
|
|
|
|
### KISClient
|
|
- ✅ 토큰 자동 관리 (파일 캐싱 23시간)
|
|
- ✅ 재시도 로직 (지수 백오프)
|
|
- ✅ 쓰로틀링 (초당 2회 기본)
|
|
- ✅ 동시 요청 수 제한 (Semaphore)
|
|
- ✅ 타임아웃 처리
|
|
|
|
### OrderManager
|
|
- ✅ 국내주식 매수/매도
|
|
- ✅ 해외주식 매수/매도
|
|
- ✅ 주문 취소
|
|
- ✅ 계좌 잔고 조회
|
|
- ✅ 실전/모의 자동 구분
|
|
|
|
### MarketDataProvider
|
|
- ✅ 현재가 조회
|
|
- ✅ 일봉/주봉/월봉 차트 (Redis 캐시 5분)
|
|
- ✅ 분봉 차트 (Redis 캐시 1분)
|
|
- ✅ 호가 조회
|
|
- ✅ 거래량 순위
|
|
- ✅ 해외주식 시세
|
|
- ✅ 페이지네이션 지원
|
|
|
|
## 설정
|
|
|
|
`backend/app/core/config.py`에서 설정 가능:
|
|
|
|
```python
|
|
class Settings(BaseSettings):
|
|
# KIS API 설정
|
|
KOREA_INVESTMENT_API_BASE_URL: str
|
|
KOREA_INVESTMENT_APP_KEY: str
|
|
KOREA_INVESTMENT_APP_SECRET: str
|
|
KOREA_INVESTMENT_ACCOUNT_NUMBER: str
|
|
|
|
# 쓰로틀링 설정
|
|
API_MIN_REQUEST_INTERVAL: float = 0.5 # 초당 2회
|
|
API_MAX_CONCURRENT_REQUESTS: int = 5
|
|
API_MAX_RETRIES: int = 3
|
|
API_RETRY_DELAY: float = 1.5
|
|
API_RETRY_BACKOFF: float = 2.0
|
|
API_TIMEOUT: float = 30.0
|
|
```
|
|
|
|
## Phase 1 리팩토링 완료 체크리스트
|
|
|
|
- [x] `trading/kis_client.py` 생성 (토큰 관리 + HTTP 요청)
|
|
- [x] `trading/order_manager.py` 생성 (주문 전담)
|
|
- [x] `trading/market_data.py` 생성 (시세 전담)
|
|
- [x] `services/korea_investment_api_adapter.py` 생성 (호환성)
|
|
- [x] 기존 API 엔드포인트 정상 동작 확인 필요
|
|
|
|
## 다음 단계 (Phase 2)
|
|
|
|
- [ ] `strategy/` 모듈 구축
|
|
- [ ] `BaseStrategy` 추상 클래스
|
|
- [ ] 기존 전략 리팩토링
|
|
|
|
---
|
|
|
|
**작성일**: 2026-03-06
|
|
**작성자**: 서영우
|