kiwoompy 0.1.5

키움증권 REST API Python 라이브러리

kiwoompy

키움증권 REST API를 Python에서 편하게 쓰기 위한 라이브러리입니다.

설치

pip install kiwoompy

uv 사용 시:

uv add kiwoompy

Python 3.12 이상이 필요합니다.

사전 준비

키움증권 OpenAPI에서 앱을 등록하고 App Key / App Secret을 발급받아야 합니다.

주의 — App Key와 App Secret은 코드에 직접 넣지 마세요. 환경 변수나 시크릿 매니저로 관리하세요.

빠른 시작

from kiwoompy import KiwoomClient

client = KiwoomClient(
    env="demo",               # "demo"(모의투자) / "real"(실계좌)
    appkey="YOUR_APP_KEY",
    secretkey="YOUR_APP_SECRET",
)

# 계좌 잔고 조회
balance = client.query.get_account_balance()
print(balance.tot_evlt_amt)   # 총평가금액

for item in balance.holdings:
    print(item.stk_nm, item.evlt_amt)

# 시장가 매수
result = client.order.buy("005930", quantity="1", trade_type="market")
print(result.ord_no)

# 지정가 매도
client.order.sell("005930", quantity="1", trade_type="limit", price="75000")

context manager도 지원합니다.

with KiwoomClient(env="demo", appkey="...", secretkey="...") as client:
    deposit = client.query.get_deposit(query_type="normal")
    print(deposit.entr)   # 예수금

기능

• OAuth2 인증 — 접근토큰 발급·만료 자동 관리
• 환경 분리 — 모의투자 / 실계좌 한 줄로 전환
• 유량 제어 — 모의 2건/초, 실전 20건/초 자동 적용
• 자동 재시도 — 네트워크 오류·5xx 지수 백오프 재시도 (최대 3회)
• 입력값 보완 — 계좌번호 상품코드 누락 시 자동 보완
• 타입 힌트 — IDE 자동완성·정적 분석 지원

에러 처리

from kiwoompy import KiwoomAuthError, KiwoomApiError

try:
    client = KiwoomClient(env="demo", appkey="wrong", secretkey="wrong")
except KiwoomAuthError as e:
    print(f"인증 실패: {e}")
except KiwoomApiError as e:
    print(f"API 오류: {e}")

예외	발생 조건
KiwoomAuthError	잘못된 키, 토큰 미발급 상태에서 API 호출
KiwoomApiError	네트워크 오류, 5xx 서버 오류, 응답 파싱 실패

문서

전체 사용법과 API 레퍼런스는 문서 사이트를 참고해 주세요.

👉 https://meonji-gogo.github.io/kiwoompy

키움증권 REST API 공지 알리미

키움증권 REST API 공지사항·변경 사항을 텔레그램으로 받아볼 수 있습니다.

👉 https://t.me/+2do4kWIhBmg3OTM1

라이선스

MIT