키움증권 API 연동 초보도 5분 설정으로 오류 줄이는 법

키움증권 API 연동 과정에서 오류가 반복된다면 대부분 환경 설정 단계에서 문제가 생긴 겁니다. OpenAPI 모듈 등록, 32비트 파이썬 환경 구성, 계좌 권한 신청 이 세 가지만 순서대로 확인해도 흔한 오류의 대부분을 잡을 수 있습니다. 이 글을 다 읽으면 키움증권 API 초기 설정을 오류 없이 완료하고 첫 데이터 조회까지 실행할 수 있습니다.

키움증권 API 연동 전, 반드시 확인해야 할 시스템 요구사항

키움증권 OpenAPI는 Windows 환경 + 32비트(x86) Python에서만 정상 동작합니다. 이 조건을 모르고 시작하면 아무리 코드를 수정해도 연결이 되지 않습니다.

필수 환경 체크리스트

항목요구 사항
운영체제Windows 10/11 (Mac·Linux 미지원)
Python 비트32비트(x86) 전용
영웅문 HTS최신 버전 설치 필수
계좌 권한Open API 사용 신청 완료
모의투자별도 신청 필요

⚠️ 주의: 64비트 Python에서 QAxWidget 로드 시 ModuleNotFoundError 또는 무응답이 발생합니다. Python 설치 전 반드시 비트 수를 확인하세요.

키움증권 API 신청 방법, 단계별 절차

키움증권 API 사용 신청은 HTS 설치 후 공식 포털에서 진행합니다.

1단계: 영웅문 HTS 설치 키움증권 공식 사이트(kiwoom.com)에서 최신 영웅문4 설치 파일을 내려받아 설치합니다.

2단계: Open API 사용 신청

  • 키움증권 OpenAPI 포털(openapi.kiwoom.com) 접속
  • 로그인 후 “사용 신청” 버튼 클릭
  • 실계좌 보유자는 즉시, 신규 개설자는 약 1 영업일 후 승인

3단계: KOA Studio 및 모듈 설치 포털 내 “[다운로드]” 메뉴에서 Open API Module과 KOA Studio를 설치합니다. KOA Studio는 API 함수 레퍼런스와 테스트 환경을 제공하는 공식 툴입니다.

4단계: OCX 등록 확인 설치 후 명령 프롬프트(관리자 권한)에서 아래 명령으로 OCX가 정상 등록되었는지 확인합니다.

regsvr32 "C:\OpenAPI\KHOPENAPI.OCX"

성공 메시지가 표시되면 모듈 등록 완료입니다.

5단계: 모의투자 신청 (테스트 필수) 실거래 전 반드시 모의투자 환경에서 테스트합니다. 영웅문 → 모의투자 서버 접속 후 별도 신청이 필요합니다.

📌 공식 포털: https://openapi.kiwoom.com

키움증권 API 오류 유형별 원인과 해결법

초보 개발자가 가장 많이 마주치는 오류 5가지와 해결 방법을 정리했습니다.

오류 1: ImportError — PyQt5 로드 실패

원인: 64비트 Python에 32비트 전용 API 모듈을 로드하려 할 때 발생합니다.

해결: Python 32비트(x86) 버전을 별도 설치하고, 해당 Python의 pip로 PyQt5를 재설치합니다.

# 32비트 Python 경로 확인 후 실행
C:\Python32\python.exe -m pip install PyQt5

오류 2: 로그인 팝업 미출력 또는 무응답

원인: OCX 등록 누락 또는 HTS 미실행 상태에서 API를 호출할 때 발생합니다.

해결: ① HTS 먼저 실행 후 로그인 → ② API 실행 순서를 반드시 지킵니다.

오류 3: -100 오류 코드 (미접속 상태)

원인: dynamicCall("CommConnect()") 호출 후 로그인 완료 이벤트를 기다리지 않고 다음 요청을 보낼 때 발생합니다.

해결: OnEventConnect 슬롯에서 로그인 완료 신호를 받은 뒤 후속 요청을 보내도록 코드 구조를 수정합니다.

오류 4: TR 요청 제한 오류

원인: 키움증권은 1초당 TR 요청 횟수를 제한합니다. 연속 요청 시 오류가 발생합니다.

해결: 요청 사이에 time.sleep(0.2) 이상의 딜레이를 삽입합니다. 공식 가이드 기준 초당 5회 이하를 권장합니다.

오류 5: 계좌 정보 미조회

원인: 모의투자 서버 접속 시 실계좌 번호로 조회를 시도하면 빈 값이 반환됩니다.

해결: 접속 서버(실거래/모의투자)에 맞는 계좌번호를 GetLoginInfo("ACCNO")로 동적으로 가져와 사용합니다.

키움증권 API 기본 코드 구조, 처음부터 올바르게 짜는 법

잘못된 초기 구조는 나중에 고치기 어렵습니다. 아래 뼈대를 기준으로 시작하면 이벤트 누락 오류를 방지할 수 있습니다.

import sys
from PyQt5.QtWidgets import QApplication
from PyQt5.QAxContainer import QAxWidget
from PyQt5.QtCore import QEventLoop

class KiwoomAPI(QAxWidget):
    def __init__(self):
        super().__init__()
        self.setControl("KHOPENAPI.KHOpenAPICtrl.1")
        self.login_loop = None

        # 이벤트 슬롯 연결
        self.OnEventConnect.connect(self._on_login)

    def login(self):
        self.login_loop = QEventLoop()
        self.dynamicCall("CommConnect()")
        self.login_loop.exec_()  # 로그인 완료까지 대기

    def _on_login(self, err_code):
        if err_code == 0:
            print("로그인 성공")
        else:
            print(f"로그인 실패: {err_code}")
        self.login_loop.exit()

app = QApplication(sys.argv)
kiwoom = KiwoomAPI()
kiwoom.login()

💡 핵심 포인트: QEventLoop를 사용해 로그인 완료를 기다리지 않으면 이후 모든 API 호출이 -100 오류를 반환합니다.

키움증권 API 모의투자 환경 세팅, 실수 없이 마무리하는 법

실제 자금 손실 없이 로직을 검증하려면 모의투자 환경 설정이 필수입니다.

모의투자 서버 전환 방법

  1. 영웅문4 실행 → 로그인 화면에서 “모의투자” 선택
  2. 모의투자 전용 ID/PW로 로그인
  3. API 코드에서 서버 구분 확인:
server = kiwoom.dynamicCall("GetLoginInfo(QString)", ["GetServerGubun"])
# 반환값 "1" → 모의투자 서버
# 반환값 "" → 실거래 서버

모의투자 주의사항

  • 모의투자 계좌번호는 실계좌와 다릅니다. 혼용 시 조회 오류 발생
  • 일부 TR(예: 실시간 시세 일부)은 모의투자에서 미지원될 수 있습니다
  • 모의투자 환경에서 충분히 검증 후 실거래 전환을 권장합니다

키움증권 API 연동 관련 자주 묻는 질문

Q: 키움증권 API는 Mac이나 Linux에서도 사용할 수 있나요?

A: 공식적으로 지원하지 않습니다. 키움증권 OpenAPI는 Windows 전용 ActiveX(OCX) 기반으로 구현되어 있어 Mac·Linux 환경에서는 동작하지 않습니다. Windows 가상머신 또는 듀얼 부팅을 사용하는 방법이 통상적인 우회 방식입니다.

Q: 파이썬 버전은 몇을 써야 키움증권 API 오류가 가장 적나요?

A: 32비트(x86) 환경이라면 Python 3.7~3.9 버전이 PyQt5와의 호환성 측면에서 일반적으로 안정적입니다. Python 3.10 이상은 일부 PyQt5 버전과 충돌이 보고된 사례가 있으므로 신규 설정 시에는 3.8 또는 3.9 32비트를 우선 고려할 수 있습니다.

Q: 키움증권 API TR 요청 제한은 어떻게 되나요?

A: 키움증권 공식 가이드 기준으로 동일 TR의 연속 요청 시 초당 5회 이하, 요청 간격 0.2초 이상을 권장합니다. 제한을 초과하면 오류 코드가 반환되며, 반복 초과 시 해당 세션의 API 사용이 일시 제한될 수 있습니다. 정확한 제한 정책은 공식 포털에서 확인을 권장합니다.

Q: 키움증권 API 모의투자와 실거래 계좌를 동시에 사용할 수 있나요?

A: 하나의 API 세션에서는 하나의 서버(모의 또는 실거래)에만 연결됩니다. 동시 접속은 지원되지 않으며, 서버 전환 시 HTS 재로그인 및 API 재접속이 필요합니다.

Q: 키움증권 OpenAPI 사용 신청 후 승인까지 얼마나 걸리나요?

A: 키움증권 계좌를 보유한 경우 통상 당일 또는 1 영업일 이내에 승인이 완료됩니다. 승인 여부는 OpenAPI 포털(openapi.kiwoom.com) 로그인 후 신청 현황 페이지에서 확인할 수 있습니다. 승인 전에는 모듈 설치는 가능하지만 실제 API 호출은 불가합니다.

마치며

키움증권 API 연동의 핵심은 32비트 Python 환경 구성, OCX 등록, 이벤트 기반 코드 구조 이 세 가지입니다. 초기 설정을 정확하게 마치면 이후 오류 빈도가 크게 줄어듭니다. 공식 포털(openapi.kiwoom.com)의 KOA Studio와 공식 가이드 문서를 함께 참고하면서 모의투자 환경에서 충분히 테스트한 뒤 실거래 환경으로 전환하는 순서를 지키시기 바랍니다. 추후 조건 검색 연동 및 자동매매 로직 구성 방법도 다룰 예정입니다.

⚠️ 본 글은 정보 제공 목적이며, 실거래 환경 적용 전 정확한 내용은 키움증권 공식 OpenAPI 포털에서 반드시 확인하시기 바랍니다.

같은 카테고리의 추천 글