kiwoompy

시작하기

kiwoompy 설치부터 접근토큰 발급까지의 기본 흐름을 안내합니다.

설치

pip install kiwoompy

uv 사용 시:

uv add kiwoompy

사전 준비

키움증권 OpenAPI 신청 후 App Key / App Secret 발급
Python 3.12 이상

!!! warning “보안 주의” App Key와 App Secret은 코드에 하드코딩하지 마세요. 환경 변수, 시크릿 매니저 등 프로젝트 환경에 맞는 방법으로 안전하게 관리하세요.

!!! tip “계좌번호 형식” 계좌번호는 "12345678-01" 형식(8자리 + 상품코드)이 원칙입니다. 상품코드를 생략하고 "12345678"만 입력해도 라이브러리가 자동으로 -01을 붙여줍니다.

기본 사용법

클라이언트 초기화

KiwoomClient 하나로 HTTP 통신·토큰 발급을 한번에 처리합니다.

from kiwoompy import KiwoomClient

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

초기화와 동시에 접근토큰이 자동으로 발급됩니다.

context manager 활용

from kiwoompy import KiwoomClient

with KiwoomClient(env="demo", appkey="...", secretkey="...") as client:
    # API 호출
    pass  # with 블록 종료 시 HTTP 세션 자동 종료

토큰 갱신

client.refresh_token(appkey="...", secretkey="...")

고급 사용 — 내부 객체 직접 접근

테스트 모킹이나 세밀한 제어가 필요할 때는 KiwoomApi / KiwoomAuth를 직접 사용할 수 있습니다.

from kiwoompy import KiwoomApi, KiwoomAuth

api = KiwoomApi(env="demo")
auth = KiwoomAuth(api)
token = auth.issue_token(appkey="...", secretkey="...")

KiwoomClient의 내부 객체에도 프로퍼티로 접근 가능합니다.

client.api    # KiwoomApi   — HTTP 통신 계층
client.auth   # KiwoomAuth  — 토큰 발급·갱신
client.query  # KiwoomQuery — 계좌·잔고·손익 조회
client.order  # KiwoomOrder — 매수·매도·정정·취소 주문

조회

client.query로 계좌·잔고·손익·주문체결 내역을 조회합니다.

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

for item in balance.holdings:
    print(item.stk_nm, item.evlt_amt)  # 종목명, 평가금액

# 미체결 주문 조회
unfilled = client.query.get_unfilled_orders(
    all_stock_type="all",   # "all": 전체, "single": 종목
    trade_type="all",       # "all" / "sell" / "buy"
    exchange="all",         # "all" / "krx" / "nxt"
)

# 예수금 조회
deposit = client.query.get_deposit(query_type="normal")  # "normal" / "estimated"
print(deposit.entr)            # 예수금
print(deposit.pymn_alow_amt)   # 출금가능금액

주문

client.order로 매수·매도·정정·취소 주문을 제출합니다.

!!! warning “실계좌 주의” env="real" 환경에서는 실제 계좌에 주문이 접수됩니다. 반드시 env="demo" (모의투자)로 먼저 테스트하세요.

# 시장가 매수
result = client.order.buy(
    "005930",
    quantity="1",
    trade_type="market",  # "market" / "limit" / "best" 등
)
print(result.ord_no)  # 주문번호

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

# 정정
modified = client.order.modify(
    original_order_no=result.ord_no,
    stock_code="005930",
    modify_quantity="1",
    modify_price="74000",
)

# 취소 (잔량 전부)
client.order.cancel(
    original_order_no=result.ord_no,
    stock_code="005930",
    cancel_quantity="0",  # "0" 입력 시 잔량 전부 취소
)

매매구분 (`trade_type`) 값 목록

값	의미
`"limit"`	보통(지정가)
`"market"`	시장가
`"conditional"`	조건부지정가
`"best"`	최유리지정가
`"priority"`	최우선지정가
`"stop"`	스톱지정가
`"mid"`	중간가
`"limit_ioc"` / `"market_ioc"` / `"best_ioc"`	IOC 계열
`"limit_fok"` / `"market_fok"` / `"best_fok"`	FOK 계열
`"pre_market"`	장시작전시간외
`"after_hours"`	시간외단일가
`"post_market"`	장마감후시간외

유량 제어

kiwoompy는 키움 공식 정책에 따라 환경별 요청 속도를 자동으로 제한합니다.

환경	기본 제한
모의투자 (`demo`)	2건/초
실계좌 (`real`)	20건/초

직접 조정이 필요할 때는 rps 파라미터를 사용합니다:

# 초당 1건으로 제한
api = KiwoomApi(env="demo", rps=1.0)

자동 재시도

네트워크 오류나 5xx 서버 오류 발생 시 지수 백오프로 최대 3회 자동 재시도합니다.

상황	동작
네트워크 오류 / 타임아웃	재시도 (최대 3회, 1→2→4초)
5xx 서버 오류	재시도 (최대 3회)
4xx 인증 오류	즉시 예외 발생 (재시도 없음)

에러 처리

from kiwoompy import KiwoomAuthError, KiwoomApiError

try:
    token = auth.issue_token(appkey="wrong", secretkey="wrong")
except KiwoomAuthError as e:
    print(f"인증 실패: {e}")       # App Key / Secret Key 오류
except KiwoomApiError as e:
    print(f"API 오류: {e}")        # 네트워크·서버 오류

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