kiwoom-rest-trade 0.1.2

키움증권 신형 REST/WebSocket API 비동기 파이썬 SDK

kiwoom-rest-trade

키움증권 신형 REST API를 위한 차세대 비동기(Async) / 동기(Sync) 통합 파이썬 SDK

본 라이브러리는 키움증권에서 새롭게 출시한 REST API 규격을 파이썬 환경에서 안전하고 신속하게 사용할 수 있도록 돕는 SDK입니다. 337개의 국내주식, 해외(미국)주식, 계좌/예수금 관련 조회를 완벽한 타입 안전성(Type-safe)과 비동기 최적화로 지원합니다.

---

핵심 기능 (Features)

• Async-First (비동기 우선): 모든 통신은 httpx[http2] 기반의 비동기 코루틴으로 처리되어 고속 자동매매 I/O에 최적화되어 있습니다.
• 동기식 래퍼(KiwoomClient) 지원: 비동기 문법이 낯선 개발자나 기존 백테스팅 프레임워크와의 연동을 위해 동적 프록시 패턴을 활용한 완전한 동기식 즉시 호출을 제공합니다.
• 337개 API 자동생성 (CodeGen): 키움 REST TR 명세를 100% 반영하여 복잡한 중첩 배열 구조까지 정밀한 Pydantic v2 데이터 모델로 완벽히 복원했습니다.
• 동시성 제어 토큰 관리: 비동기 Lock을 적용하여 토큰 만료 임박 시 동시 호출 상태에서도 백그라운드에서 오직 1회만 토큰을 안전하게 갱신합니다.
• 정밀 유량 제어 (Rate Limiter): 국내주식(초당 5회), 미국주식(초당 10회, 피크타임 동적 지연보정) 등 호출 한도를 준수하도록 대기(asyncio.sleep)를 자동 제어합니다.

---

지원 API 목록 (Supported APIs)

본 라이브러리는 키움증권 REST API의 총 337개 엔드포인트를 완벽하게 지원합니다. 각 키움 API ID에 1대1 매핑되는 파이썬 클라이언트 호출 경로와 상세 설명은 아래 링크된 가이드 문서에서 바로 찾아 복사해 사용하실 수 있습니다.

👉 전체 337개 지원 API 목록 및 매핑 가이드 (docs/API_LIST.md)

---

설치 방법 (Installation)

파이썬 3.10 이상 환경에서 uv 또는 pip를 사용해 쉽게 설치할 수 있습니다.

# pip를 사용하는 경우
pip install kiwoom-rest-trade

# uv를 사용하는 경우
uv add kiwoom-rest-trade

---

빠른 시작 (Quick Start)

사용 전 프로젝트 루트에 .env 파일(가이드는 .env.example 참고)을 생성하고 키를 설정하십시오.

1. 비동기식 호출 예시 (AsyncKiwoomClient)

import asyncio
from kiwoom import AsyncKiwoomClient
from kiwoom.models.domestic import Ka10001Request

async def main():
    # 클라이언트 초기화
    client = AsyncKiwoomClient(
        appkey="YOUR_APP_KEY", 
        secretkey="YOUR_SECRET_KEY", 
        is_mock=True  # 모의투자 모드
    )
    
    # 삼성전자(005930) 주가 조회
    req = Ka10001Request(stk_cd="005930")
    resp = await client.domestic.ka10001(req)
    
    print(f"종목명: {resp.stk_nm}")
    print(f"현재가: {resp.cur_prc}원")
    print(f"등락률: {resp.flu_rt}%")

if __name__ == "__main__":
    asyncio.run(main())

2. 동기식 호출 예시 (KiwoomClient)

from kiwoom import KiwoomClient
from kiwoom.models.domestic import Ka10001Request

# 동기 클라이언트는 내부적으로 비동기 통신을 변환 처리합니다.
client = KiwoomClient(
    appkey="YOUR_APP_KEY", 
    secretkey="YOUR_SECRET_KEY", 
    is_mock=True
)

# await 없이 바로 동기식으로 데이터를 조회합니다.
req = Ka10001Request(stk_cd="005930")
resp = client.domestic.ka10001(req)

print(f"종목명: {resp.stk_nm}")
print(f"현재가: {resp.cur_prc}원")

---

로드맵 (Roadmap)

• v0.1.0: REST API 기반 구축, 337개 조회 API 자동 생성, 토큰 자동 갱신 및 비동기 유량 제어기 구현 완료. (E2E 실서버 연동 검증 통과)
• v0.2.0: 국내주식/해외주식 비동기 실주문(Order) 및 체결 정합성 검증 추가.
• v0.3.0: WebSocket 기반 실시간 호가/체결 스트리밍 수신 모듈(websocket.py) 탑재.

---

라이선스 (License)

본 라이브러리는 MIT License 하에 배포됩니다.