콘텐츠로 이동

왜 kiwoom-client 인가

키움증권으로 파이썬 자동매매·데이터 수집을 하는 방법은 크게 둘입니다. 오래된 OpenAPI+(OCX/COM) 를 감싼 라이브러리, 그리고 새로 공개된 키움 REST API 를 감싼 라이브러리. 이 페이지는 둘을, 그리고 REST 쪽 대안들을 사실대로 비교합니다. 어느 것이 맞는지는 하려는 일에 달려 있습니다 — 아래 "다른 것을 고를 때" 도 같이 보세요.

OpenAPI+(OCX) 와 REST API

항목 OpenAPI+ (OCX/COM) 키움 REST API
연동 방식 Windows COM 컨트롤 + 이벤트 콜백 HTTPS(JSON) + WebSocket
운영체제 Windows 전용 Windows · macOS · Linux
파이썬 오랫동안 32bit 파이썬 전용이었고, Qt 이벤트 루프에 묶임 64bit, 일반 asyncio/스레드
서버·도커·클라우드 배포 GUI 세션이 필요해 어렵다 헤드리스로 가능
로그인 OpenAPI 로그인 창(사람 입력 또는 자동로그인 설정) 앱키·시크릿키로 토큰 발급
인증 단위 사용자 PC 설치 앱 등록(포털에서 API 사용신청)

REST API 로 옮기면 Linux 서버나 맥에서, 사람이 로그인 창을 누르지 않고 돌릴 수 있습니다. 대신 OpenAPI+ 에만 있던 기능이 REST 에 아직 없을 수 있으니, 꼭 필요한 TR 은 키움 REST API 가이드에서 먼저 찾아보세요. kiwoom-client 가 감싼 목록은 엔드포인트 전체 목록에, OpenAPI+ TR·함수와의 대응은 OpenAPI+(OCX) · pykiwoom 에서 옮겨 오기에 있습니다.

파이썬 라이브러리 한눈에

2026-11-21 PyPI 메타데이터와 각 프로젝트 README 에 적힌 내용 기준입니다. 버전과 기능은 바뀌므로 고르기 전에 각 프로젝트 페이지를 확인하세요.

키움증권 공식

저장소 / 패키지 최신 (올린 날) 파이썬 라이선스 README 에 적힌 내용
Kiwoom-Securities/Kiwoom-REST-API · PyPI kwcli kwcli 1.0.3 (2026-09) ≥ 3.13 키움증권 자체 라이선스(키움 OpenAPI 이용 목적으로 사용 허락) API 337종 스펙(국내주식·미국주식), 함수별 예제 362개, Postman 컬렉션, CLI kiwoomcli, MCP 서버 2종(스펙 검색용·실행용 — 주문은 명시 허용 시에만)

키움증권이 직접 내는 저장소라 API 스펙의 정본에 가장 가깝고, 미국주식까지 다룹니다. 아래 비교는 이 공식 도구와 겹치는 부분이 있다는 것을 전제로 읽어 주세요.

OpenAPI+(OCX) 래퍼

패키지 최신 버전 (올린 날) 파이썬 비고
pykiwoom 0.1.6 (2024-01) 명시 없음 pywin32·PyQt5 의존. 한국어 자료가 가장 많다
KOAPY 0.9.0 (2022-09) 3.8–3.10 gRPC 서버로 OCX 를 원격 호출
kiwoom 1.5.0 (2025-08) 3.8–3.11 PyQt5 기반의 얇은 래퍼

REST API 래퍼

패키지 최신 버전 (올린 날) 파이썬 라이선스 README 에 적힌 특징
kiwoom-client (이 프로젝트) PyPI 참고 ≥ 3.10 MIT sync·async 같은 표면, 토큰 자동 갱신, TR별 Rate Limiter, 실시간 WebSocket, MCP 서버(실주문 opt-in)
pykiwoom-rest 2.2.0 (2026-07) ≥ 3.8 (MCP 는 ≥ 3.10) MIT 라이브러리 + kiwoom CLI + MCP 서버, pandas 출력
kiwoom-cli / kiwoom-mcp 2.14.0 / 0.1.2 (2026-07) ≥ 3.10 자체 라이선스 / Apache-2.0 CLI 중심. MCP 는 --allow-orders 일 때만 주문 도구 등록, 주문 사전점검·dry-run
kiwoompy 0.1.6 (2026-03) ≥ 3.12 MIT 응답을 속성으로 읽는 모델(balance.tot_evlt_amt), 문서 사이트
kiwoom-rest-api 0.1.12 (2025-06) ≥ 3.9 명시 없음 모듈별 클래스 + CLI

kiwoom-client 가 다른 점

모두 코드와 테스트로 확인할 수 있는 것만 적습니다.

  • 엔드포인트를 코드에서 센다. REST 182개·조건검색 4종·실시간 19종을 15개 모듈로 감쌌고, 그 목록은 소스에서 생성됩니다 (엔드포인트 전체 목록). 메서드 이름 옆에 키움 공식 api_id(ka10001 등)가 그대로 붙어 있어 공식 가이드와 바로 대조됩니다.
  • sync 와 async 가 같은 표면. KiwoomAPI 와 AsyncKiwoomAPI 는 같은 모듈·같은 메서드를 갖습니다. 스크립트로 시작해 asyncio.gather 로 넘어갈 때 코드를 다시 짜지 않아도 됩니다.
  • 오래 도는 봇을 위한 기본값. 토큰은 만료 전에 갱신되고 401 이면 재발급 후 재시도합니다. Rate Limit 은 실측한 TR별 한도 (약 1 req/s, 버스트 2)에 맞춘 토큰 버킷이고, 429 가 나면 백오프 후 다시 보냅니다.
  • 에이전트가 실주문을 모르게. 내장 MCP 서버는 실전투자 서버에서 KIWOOM_MCP_ALLOW_LIVE_ORDERS=true 를 켜기 전까지 주문 도구 12개를 등록하지 않습니다. 모의투자에서는 항상 쓸 수 있습니다. 키움 공식 MCP·플러그인을 쓰면서 주문 내용(금액·수량 상한, 시장가 매수, 반복 전송, 하루 횟수)까지 막고 싶다면 같은 저자의 Claude Code 훅 kiwoom-order-guard를 함께 쓰세요.
  • 계산 가능한 응답. to_dataframe()·to_number() 가 "+70000", "1,234,567" 같은 문자열을 숫자로 바꾸고, 종목코드처럼 앞자리 0 이 의미 있는 값은 문자열로 남깁니다. round_to_tick() 은 지정가를 KRX 호가단위에 맞춥니다.
  • 타입 정보 포함. py.typed 를 배포하고 CI 에서 mypy 를 돌립니다.

다른 것을 고를 때

  • 터미널에서 바로 조회·주문하는 CLI 가 주목적이면 kiwoom-cli 나 pykiwoom-rest 의 CLI 가 더 맞습니다. kiwoom-client 는 라이브러리와 MCP 서버만 제공합니다.
  • 응답을 속성 접근 모델로 받고 싶다면 kiwoompy 를 보세요. kiwoom-client 는 키움 응답 JSON(dict) 을 그대로 돌려주고, 필요하면 to_dataframe() 으로 바꿉니다.
  • 키움증권이 직접 관리하는 도구, 또는 미국주식 API 가 필요하다면 키움 공식 저장소와 kwcli 를 쓰세요. kiwoom-client 는 국내주식 REST 만 감쌉니다.
  • OpenAPI+ 에만 있는 기능에 의존한다면 아직은 pykiwoom 같은 OCX 래퍼가 필요할 수 있습니다.
  • 파이썬 3.8·3.9 를 써야 한다면 kiwoom-client(≥ 3.10)는 맞지 않습니다.

반대로 MIT 라이선스의 pip install 라이브러리로 국내주식 REST 를 sync·async 양쪽에서 쓰고, 같은 패키지로 MCP 서버까지 띄우고 싶다면 kiwoom-client 가 맞습니다.

비교에 틀린 내용이 있거나 빠진 프로젝트가 있으면 이슈로 알려 주세요. 바로 고치겠습니다.

kiwoom-client 는 키움증권과 무관한 비공식 오픈소스 프로젝트입니다.