편의 기능 — 짧게, 실수 없이¶
엔드포인트 182개를 그대로 부르는 것 말고, 자주 하는 일을 줄이고 흔한 실수를 막는 도구들입니다. 전부 기존 동작은 그대로 두고 더한 것이라, 원래 쓰던 코드는 바꿀 필요가 없습니다.
환경변수로 시작하기 — from_env()¶
from kiwoom_client import KiwoomAPI
api = KiwoomAPI.from_env(is_mock=True) # KIWOOM_APP_KEY / KIWOOM_APP_SECRET
api = KiwoomAPI.from_env(".env", is_mock=True) # .env 파일도 읽는다 (새 의존성 없음)
| 변수 | 뜻 |
|---|---|
KIWOOM_APP_KEY |
앱키 (필수) |
KIWOOM_APP_SECRET |
시크릿키 (필수) |
KIWOOM_IS_MOCK |
true 모의투자 / false 실전투자 |
- MCP 서버와 같은 이름이라
.env하나로 둘 다 씁니다. - 우선순위:
is_mock=인자 > 프로세스 환경변수 >.env파일. KIWOOM_IS_MOCK은true/false,1/0,yes/no,on/off만 받습니다.ture같은 오타는 실전투자로 넘어가지 않고ValueError입니다.- 어디에도 없으면 실전투자 서버(
is_mock=False, 생성자·MCP 서버와 같은 기본값)에 붙고kiwoom_client로거에 경고를 남깁니다. 처음엔is_mock=True를 직접 넘기세요. - 나머지 인자(
rate_limit,max_retries,timeout...)는 그대로 생성자로 넘어갑니다.AsyncKiwoomAPI.from_env()도 같습니다.
종목명 ↔ 종목코드 — find_stock()¶
api.find_stock("삼성") # [{'code': '005930', 'name': '삼성전자', 'marketName': ...}, ...]
api.stock_code("SK하이닉스") # '000660'
api.stock_list() # 코스피 + 코스닥 전 종목
- 종목정보 리스트(ka10099)를 시장마다 전 페이지 한 번 받아 클라이언트에 캐시합니다.
refresh=True로 다시 받고,cache_ttl=초로 자동 만료합니다. - 순서: 정확한 코드 > 정확한 이름 > 이름 앞부분 > 코드 앞부분 > 이름 일부. 대소문자·공백은 무시합니다.
stock_code()는 이름이 정확히 한 종목과 같을 때만 코드를 주고, 아니면 후보를 담은LookupError입니다.- 다른 시장:
markets=[StockListMarket.ETF](아래 코드값 참고).
코드값 상수 — kiwoom_client.codes¶
키움은 옵션을 짧은 문자열로 받고, 같은 필드 이름이 TR마다 다른 코드를 씁니다. 이름 붙은 상수를 쓰면 오타가 바로 드러납니다.
모두 str 이라 그대로 넘기면 원래 코드값이 전송됩니다.
from kiwoom_client import Exchange, OrderType
api.order.buy_order(
dmst_stex_tp=Exchange.KRX, stk_cd="005930", ord_qty="10",
ord_uv="70000", trde_tp=OrderType.LIMIT, # "0" 보통(지정가)
)
| 상수 | 필드 | 값 |
|---|---|---|
Exchange |
주문 dmst_stex_tp |
KRX · NXT · SOR |
OrderType |
주문 trde_tp |
LIMIT="0", MARKET="3", STOP_LIMIT="28" 등 18종 |
QueryExchange |
조회 stex_tp |
KRX="1", NXT="2", ALL="3"(통합) |
Market |
순위·종목 TR mrkt_tp |
ALL="000", KOSPI="001", KOSDAQ="101" |
StockListMarket |
ka10099 mrkt_tp |
KOSPI="0", KOSDAQ="10", ETF="8" 등 16종 |
AdjustedPrice |
차트 upd_stkpc_tp |
RAW="0", ADJUSTED="1" |
PriceChangeSign |
응답 pred_pre_sig |
1 상한가 · 2 상승 · 3 보합 · 4 하한가 · 5 하락 |
exchange_stock_code("005930", Exchange.NXT) 는 시세·차트 TR 이 받는 거래소별 코드 "005930_NX" 를 만듭니다(SOR 은 _AL).
값은 키움 REST API 가이드에서 TR별로 확인한 것만 넣었습니다.
차트 → OHLCV DataFrame — to_ohlcv()¶
from kiwoom_client import to_ohlcv
resp = api.chart.stock_daily_chart(stk_cd="005930", base_dt="20260327", upd_stkpc_tp="1")
df = to_ohlcv(resp) # open/high/low/close/volume, DatetimeIndex, 오래된 순
- 주식·업종·금현물의 틱·분·일·주·월·년봉을 모두 받습니다.
request_all()의 리스트도 됩니다. - 분·틱봉 가격 앞의
+/-는 등락 방향이지 음수가 아니라서 떼어 냅니다. - 거래대금처럼 다른 필드도 필요하면
keep=["trde_prica"](단위가 TR마다 다릅니다: 일봉 백만원, 주·월봉 원). - 업종 지수 값은 키움이 보낸 그대로(소수점 제거된 값)입니다.
- pandas 가 필요합니다:
pip install 'kiwoom-client[pandas]'. 원 필드 전부가 필요하면 기존to_dataframe().
호가 계산 — add_ticks() · ticks_between()¶
from kiwoom_client import add_ticks, is_on_tick, round_up_to_tick, ticks_between
add_ticks(49_950, 2) # Decimal('50100') — 5만원 경계에서 호가단위가 50 → 100
add_ticks(2_000, -1) # Decimal('1999') — 1995 가 아니다
ticks_between(49_900, 50_100) # 3
round_up_to_tick(70_101) # Decimal('70200') — round_to_tick() 의 올림판
is_on_tick(70_150) # False
손절·익절가를 "N틱 아래/위" 로 잡을 때 구간 경계에서 틀리지 않게 합니다. 유효 호가가 아닌 값을 넣으면 ValueError 입니다.
기존 tick_size()·round_to_tick()·ticks_in() 결과는 바뀌지 않았습니다.
예외 — 무엇이 잘못됐는지 타입으로¶
from kiwoom_client import KiwoomAPIError, KiwoomRateLimitError, KiwoomServerMismatchError
try:
api.stock_info.basic_stock_info(stk_cd="005930")
except KiwoomServerMismatchError as e: # 모의/실전 키 불일치 (8030/8031)
print(e.hint) # 지금 연결된 서버와 맞는 is_mock 안내
except KiwoomRateLimitError: # 한도 초과 — 자동 재시도 뒤에도
...
except KiwoomAPIError as e: # 그 밖의 return_code != 0 (기존과 같다)
print(e.code, e.error_code, e.message)
KiwoomError
├── KiwoomAuthError 토큰 발급·폐기 실패
├── KiwoomWebSocketError WebSocket 로그인·프로토콜 실패
└── KiwoomAPIError return_code != 0
├── KiwoomTokenError 토큰 거부 (return_code 3)
│ └── KiwoomServerMismatchError 모의/실전 불일치
├── KiwoomRateLimitError 호출 한도 초과 (return_code 5)
├── KiwoomRequestError 파라미터·헤더 오류
│ └── KiwoomStockNotFoundError 종목코드 없음
└── KiwoomUnsupportedError 모의투자·법인 미지원 API
- 세분 예외는 모두
KiwoomAPIError라서 기존except KiwoomAPIError가 그대로 잡습니다.code·message·response도 그대로입니다. error_code는return_msg안의 4자리 코드([8005:...])입니다.- 원인을 아는 오류는
str(e)둘째 줄에힌트:가 붙습니다(e.hint). 토큰 발급 실패(KiwoomAuthError)도 같습니다.
명령줄 — kiwoom¶
kiwoom quote 005930 --mock # 현재가 (종목명도 됩니다: kiwoom quote 삼성전자)
kiwoom chart 005930 --daily -n 10 # --weekly --monthly --yearly --minute --tick
kiwoom balance --mock # 계좌평가잔고 (kt00018)
kiwoom find 하이닉스 --mock
kiwoom endpoints 체결 # 메서드 ↔ TR 찾기 (키 없이)
kiwoom --json quote 005930 # 원 응답 JSON
키는 from_env() 와 같이 환경변수에서 읽고 --env-file 로 .env 를 지정할 수 있습니다. --mock/--live 가 KIWOOM_IS_MOCK 보다 우선합니다.
조회만 합니다 — 주문·토큰 폐기 명령은 일부러 없습니다. python -m kiwoom_client 로도 실행됩니다.
디버깅 — repr · 로그 · timeout¶
print(api)
# KiwoomAPI(server='mock', base_url='https://mockapi.kiwoom.com', app_key='****AbCd', token='set')
print(api)로 어느 서버에 붙었는지 바로 봅니다. 시크릿키와 토큰은 일부도 보이지 않습니다.- 요청 추적:
logging.getLogger("kiwoom_client").setLevel(logging.DEBUG)— api-id·HTTP 상태·return_code·재시도·토큰 재발급이 남고, 헤더(토큰)와 본문(계좌번호)은 남지 않습니다. KiwoomAPI(..., timeout=10.0)— HTTP 타임아웃(초 또는httpx.Timeout). 기본 30초.