kiwoom-rest-trade

💡 kiwoom-rest-trade 프로젝트 기획서

1. 기획 배경 (Why?)

• 기존 환경의 한계: 기존 키움증권 OpenAPI(OCX 방식)는 Windows 32비트 환경에 묶여 있어, 최신 개발 트렌드(Mac/Linux 활용, 64비트 환경)나 클라우드 서버 배포가 불가능했습니다.
• 차세대 API의 등장: 키움증권에서 OS 제약이 없는 REST API를 출시했지만, 일반 투자자가 날것(Raw)의 HTTP 요청과 보안 토큰 관리를 직접 구현하며 쓰기에는 진입장벽이 높습니다.
• 보안 불안감: PyPI에 올라와 있는 기존 서드파티 패키지들은 소스 코드가 불투명하거나, 내 소중한 API Key가 안전하게 관리되는지 신뢰하기 어렵습니다.
• 결론: 현대적인 퀀트/자동매매 개발자들이 “믿고 쓸 수 있는, 안전하고 빠른 크로스 플랫폼(Mac/Linux/Win) 키움증권 매매 라이브러리”가 절대적으로 필요한 시점입니다.

---

2. 제품 정의 및 타깃 사용자 (Who & What)

• 제품 정의: 키움증권 신형 REST API를 파이썬에서 단 몇 줄로 다룰 수 있게 해주는 개발자용 오픈소스 도구(SDK)
• 타깃 사용자
  • Mac이나 Linux 환경에서 주식 자동매매 프로그램을 돌리고 싶은 개인 투자자
  • 그리드 매매, 알고리즘 매매 등 분초를 다투는 실전 비동기 퀀트 트레이더
  • 기존 32비트 Windows 환경의 구형 프로그램에서 탈출하고 싶은 개발자

---

3. 핵심 차별화 가치 (Core Values)

• 100% 투명한 보안: 소스 코드를 완전히 공개하여, 사용자의 자산과 Key를 외부로 절대 빼돌리지 않는다는 안전성을 보장합니다.
• 크로스 플랫폼 & 초고속: Windows는 물론, Mac(M1/M2/M4 등)과 Linux 환경에서도 아무런 제약 없이 작동합니다.
• 예외 제어권 보장 (Trader-First): 시스템이 먹통 되었을 때 라이브러리가 임의로 대기하는 답답함 없이, 에러를 즉시 투자자(개발자)에게 던져주어 실전 매매에서 유연한 위기 대처가 가능하게 합니다.

---

4. 서비스 기능 명세 (What it does)

🔐 1) 스마트 인증 (Auth)

• 사용자는 App Key와 Secret Key만 입력하면 끝.
• 유효 시간 분 단위 체크 후, 만료되기 전에 토큰을 알아서 갱신해 주는 똑똑한 인증 시스템.

🇰🇷🇺🇸 2) 글로벌 통합 매매 (Global Trading)

• 국내 주식과 해외(미국) 주식을 하나의 라이브러리 안에서 동일한 방식으로 처리.
• 시세 조회 (현재가, 호가, 차트 데이터 수집)
• 자산 조회 (내 계좌 잔고, 예수금, 보유 종목 및 수익률 현황)
• 주문 기능 (매수, 매도, 정정, 취소 주문 전송)

⚡ 3) 실시간 데이터 스트리밍 (Real-time Stream)

• 웹소켓(WebSocket) 기술을 활용해 실시간 호가 변화 및 체결 데이터를 실시간으로 받아보는 기능.
• 내 주문이 체결되는 순간 즉시 프로그램에 알림을 주는 ‘계좌 체결 통보’ 기능.

🐍 4) 파이썬 친화적 에러 가이드 (Error Handling)

• 키움 서버가 주는 알 수 없는 영문/숫자 에러 코드 대신, KiwoomOrderError(주문 에러), KiwoomRateLimitError(호출 제한 초과) 등 직관적인 한글/파이썬 예외로 번역해서 제공.

---

5. 최종 기대 효과

• 이 라이브러리를 사용하는 개발자는 복잡한 통신이나 보안 처리에 시간을 낭비하지 않고, 오직 자신만의 ‘매매 전략(알고리즘)’ 개발에만 집중할 수 있게 됩니다.

---

6. 기술 요구사항 (Technical Requirements)

• 지원 Python 버전: Python 3.10 이상
• 비동기 전략: asyncio 기반 완전 비동기 설계 (동기 래퍼 별도 제공)
• 핵심 의존성:
  • HTTP 클라이언트: httpx (동기/비동기 통합 지원)
  • WebSocket: websockets
  • 설정 관리: pydantic (타입 안전성 보장)
• API 호출 제한 (키움 공식 기준):
  • 국내주식 주문/조회 TR: 1초당 5회
  • 미국주식 주문 TR: 1초당 10회 (피크타임 3회)
  • 미국주식 조회 TR: 1초당 5회 (피크타임 3회)
  • 모의투자: 1초당 1회

---

7. 버전별 기능 범위 (Milestone Scope)

🚀 v0.1.0 — MVP (핵심 기능 우선)

• 토큰 발급 및 자동 갱신 인증 시스템
• 국내 주식 현재가 조회
• 국내 주식 호가 조회
• 국내 주식 매수 / 매도 / 정정 / 취소 주문
• 기본 커스텀 예외 클래스 (KiwoomAPIError, KiwoomAuthError)
• PyPI 최초 배포

📈 v0.2.0 — 글로벌 & 자산 조회

• 미국 주식 시세 조회 및 매매 주문
• 국내/미국 계좌 잔고 및 보유 종목 조회
• 예수금 조회
• Rate Limit 자동 감지 및 재시도 로직 (KiwoomRateLimitError)

⚡ v0.3.0 — 실시간 스트리밍

• WebSocket 기반 실시간 체결가/호가 스트리밍
• 계좌 체결 통보 (내 주문 실시간 알림)
• 실시간 조건검색 (국내/미국 각 10건)

🏆 v1.0.0 — 안정화 & 완성

• 동기 래퍼 API 제공 (비동기 미숙련 사용자 배려)
• 전체 엔드포인트 커버리지 달성
• 공식 문서 (ReadTheDocs 또는 MkDocs) 완성
• 100% 타입 힌트 (mypy strict 통과)
• 단위/통합 테스트 커버리지 80% 이상

This site is open source. Improve this page.