한국어 | English

kiwoom-rest-api — 키움증권 REST API Python 라이브러리

키움증권 OpenAPI를 대체하는 Python REST API 래퍼. COM/OCX 없이 Windows · macOS · Linux 어디서나 국내주식 자동매매 · 시세조회 · 실시간 WebSocket을 사용할 수 있습니다. 토큰 자동 갱신으로 봇이 만료에 죽지 않고, sync / async 양쪽을 지원합니다. 186개 엔드포인트 · 19종 실시간 데이터 · 모의투자/실전투자 지원.

키움증권 REST API를 Python으로 쉽게 사용할 수 있는 래퍼 라이브러리입니다. 기존 키움 **OpenAPI+(OCX/COM)**나 pykiwoom과 달리, 32bit·Windows 제약 없이 64bit Python과 서버(헤드리스) 환경에서 그대로 동작합니다.

국내주식 186개 엔드포인트(REST 182 + 조건검색 4)와 19종 실시간 WebSocket 데이터를 지원합니다.

검색 키워드: 키움 OpenAPI 파이썬, 키움증권 자동매매 파이썬, 키움 REST API, pykiwoom 대안, 키움 모의투자 파이썬, KOSPI/KOSDAQ 시세 조회, 키움 asyncio, 키움 토큰 갱신

목차

• 왜 이 라이브러리인가?
• 기존 키움 OpenAPI / pykiwoom 과 무엇이 다른가?
• 설치
• 사전 준비
• 빠른 시작
• asyncio 사용법
• 응답을 숫자·DataFrame으로 받기
• 실시간 WebSocket 데이터
• 연속 조회 (페이지네이션)
• 에러 처리
• 요청 제한 (Rate Limit)
• 자주 묻는 질문 (FAQ)
• 지원 API 목록

왜 이 라이브러리인가?

• 크로스 플랫폼: REST API 기반이라 Windows, macOS, Linux 어디서나 동작합니다. COM/OCX 방식과 달리 서버 환경에서도 사용 가능합니다.
• 자동 토큰 관리: 토큰을 알아서 발급하고, 만료 전에 갱신하고, 401이 나면 재발급 후 재시도합니다. 장시간 도는 봇이 토큰 만료로 죽지 않습니다.
• sync / async 양쪽 지원: KiwoomAPI와 AsyncKiwoomAPI가 같은 API를 제공합니다.
• 자동 페이지네이션: request_all()로 연속조회를 한 줄에 처리합니다.
• 내장 Rate Limiter: TR(api_id)별 토큰 버킷으로 호출 제한을 자동 관리합니다.
• 바로 쓰는 응답: to_dataframe()이 "+70000" 같은 문자열을 숫자로 바꿔 DataFrame으로 넘겨줍니다.
• 완전한 커버리지: 국내주식 182개 REST 엔드포인트 + 조건검색 4종 + 19종 실시간 WebSocket 데이터를 지원합니다.

기존 키움 OpenAPI / pykiwoom 과 무엇이 다른가?

기존 키움 **OpenAPI+(OCX/COM)**나 이를 감싼 pykiwoom은 32bit Windows에 묶여 있어 서버 배포·자동화가 어렵습니다. 이 라이브러리는 키움의 신규 REST API를 사용하므로 그 제약이 없습니다.

이미 OCX 기반 코드를 쓰고 있다면, REST 방식으로 전환할 때 GUI 의존성과 32bit 제약을 한 번에 제거할 수 있습니다.

설치

pip install kiwoom-client

pandas 변환(to_dataframe())까지 함께 쓰려면:

pip install 'kiwoom-client[pandas]'

또는 uv 사용:

uv add kiwoom-client

소스에서 설치:

git clone https://github.com/younghwan91/kiwoom-rest-api.git
cd kiwoom-rest-api
pip install -e .
# 또는
uv pip install -e .

사전 준비

1. 키움 REST API 포털에 가입합니다.
2. API 사용신청을 통해 앱키(appkey)와 시크릿키(secretkey)를 발급받습니다.
3. 환경변수 설정은 .env.example을 참고하세요.
4. 처음에는 모의투자(is_mock=True)로 테스트한 뒤, 실전투자로 전환하세요.

빠른 시작

1단계: 연결

from kiwoom_rest_api import KiwoomAPI

# 모의투자 서버로 연결
api = KiwoomAPI(
    app_key="발급받은_앱키",
    app_secret="발급받은_시크릿키",
    is_mock=True,  # True=모의투자, False=실전투자
)

접근토큰은 첫 호출에서 자동 발급되고 만료 전에 갱신되므로 따로 할 일이 없습니다. 키가 올바른지 즉시 확인하고 싶다면 api.login()을 호출하세요 (선택).

2단계: 종목 조회

# 삼성전자(005930) 기본 정보 조회
info = api.stock_info.basic_stock_info(stk_cd="005930")
print(info)

# 삼성전자 일봉 차트 조회
chart = api.chart.stock_daily_chart(stk_cd="005930", base_dt="20260326")

# 당일 거래량 상위 종목 조회
ranking = api.ranking.top_volume_today()

3단계: 계좌 조회

# 내 계좌 평가 현황
evaluation = api.account.account_evaluation()

# 예수금 상세 조회
deposit = api.account.deposit_detail()

# 체결 잔고 조회
position = api.account.filled_position()

# 미체결 주문 조회
unfilled = api.account.unfilled_orders()

4단계: 주문

# 삼성전자 10주 지정가 매수
result = api.order.buy_order(
    dmst_stex_tp="01",   # 거래소 구분 (01: KRX)
    stk_cd="005930",     # 종목코드
    ord_qty=10,          # 주문 수량
    trde_tp="00",        # 주문 유형 (00: 지정가)
    ord_uv=70000,        # 주문 단가
)

# 매도 주문
api.order.sell_order(
    dmst_stex_tp="01",
    stk_cd="005930",
    ord_qty=10,
    trde_tp="00",
    ord_uv=75000,
)

# 주문 정정
api.order.modify_order(org_ord_no="원래주문번호", ord_qty=5, ord_uv=71000)

# 주문 취소
api.order.cancel_order(org_ord_no="원래주문번호", ord_qty=5)

5단계: 정리

api.logout()  # 토큰 폐기 (선택)
api.close()   # 연결 종료

# with 문을 쓰면 close()는 자동입니다
with KiwoomAPI(app_key="앱키", app_secret="시크릿키", is_mock=True) as api:
    info = api.stock_info.basic_stock_info(stk_cd="005930")

asyncio 사용법

AsyncKiwoomAPI는 KiwoomAPI와 같은 엔드포인트를 제공하며, 호출 앞에 await만 붙이면 됩니다.

import asyncio
from kiwoom_rest_api import AsyncKiwoomAPI

async def main():
    async with AsyncKiwoomAPI(app_key="앱키", app_secret="시크릿키", is_mock=True) as api:
        # 서로 다른 TR은 동시에 나간다 — 직렬로 돌리면 3배 걸린다
        info, chart, ranking = await asyncio.gather(
            api.stock_info.basic_stock_info(stk_cd="005930"),
            api.chart.stock_daily_chart(stk_cd="005930", base_dt="20260326"),
            api.ranking.top_volume_today(
                mrkt_tp="0", stk_cnd="0", trde_qty_tp="0",
                prc_tp="0", trde_amt_tp="0", updn_tp="0",
            ),
        )
        print(info["stk_nm"])

asyncio.run(main())

Rate Limiter는 TR(api_id)별로 걸립니다. 서로 다른 TR은 서로를 막지 않고 동시에 나가며, 같은 TR을 반복 호출할 때만 초당 1건으로 조여집니다. 전체 예제는 examples/async_usage.py를 참고하세요.

응답을 숫자·DataFrame으로 받기

키움은 모든 값을 문자열로 돌려줍니다. 가격은 "+70000", 등락률은 "-1.23", 거래량은 "1,234,567" 같은 식이라 그대로는 계산에 쓸 수 없습니다.

from kiwoom_rest_api import to_dataframe, to_number, normalize

result = api.ranking.top_volume_today(...)

# 페이로드 키를 자동으로 찾아 DataFrame으로 변환 (문자열 → 숫자 포함)
df = to_dataframe(result)
print(df["cur_prc"].mean())   # 바로 계산 가능

# dict 그대로 쓰고 싶다면
data = normalize(result)
price = to_number("+70000")   # 70000

종목코드("005930")처럼 앞자리 0이 의미를 갖는 값과, base_dt 같은 날짜·식별자 필드는 숫자로 바꾸지 않고 문자열로 남깁니다.

to_dataframe()에는 pandas가 필요합니다:

pip install 'kiwoom-client[pandas]'

실시간 WebSocket 데이터

실시간 체결가, 호가, 잔고 변동 등을 WebSocket으로 수신할 수 있습니다.

import asyncio
from kiwoom_rest_api import KiwoomAPI

api = KiwoomAPI(app_key="앱키", app_secret="시크릿키")
ws = api.create_websocket()

async def main():
    # connect()가 LOGIN 핸드셰이크까지 끝냅니다. 실패하면 KiwoomWebSocketError
    await ws.connect()

    # 콜백은 REAL 프레임의 항목 하나를 받습니다:
    # {"type": "0B", "item": "005930", "values": {"10": "+70000", ...}}
    ws.on("0B", lambda d: print(f"체결 {d['item']}: {d['values'].get('10')}"))
    ws.on("0D", lambda d: print(f"호가 {d['item']}: {d['values'].get('41')}"))

    # async 콜백도 그대로 등록할 수 있습니다
    async def save(d): ...
    ws.on("0B", save)

    # 삼성전자 실시간 체결+호가 구독
    await ws.subscribe("0B", "005930")
    await ws.subscribe(["0B", "0D"], ["005930", "000660", "035420"])

    # PING 응답과 재연결(재로그인·구독 복원)은 listen()이 알아서 처리합니다
    await ws.listen()

asyncio.run(main())

values의 키는 키움 FID 번호입니다(10=현재가, 13=누적거래량, 41=매도최우선호가).

조건검색

조건검색도 같은 WebSocket을 씁니다. api.condition_search가 요청 페이로드를 만들고, ws.send()로 보낸 뒤 ws.on_trnm()으로 응답을 받습니다.

await ws.connect()
ws.on_trnm("CNSRLST", lambda d: print("조건식 목록:", d["data"]))
ws.on_trnm("CNSRREQ", lambda d: print("검색 결과:", d.get("data")))

# 조건식 목록을 먼저 조회해야 seq를 알 수 있습니다
await ws.send(api.condition_search.condition_list())

# seq로 검색 (search_type="1"이면 실시간 편입/이탈까지 수신)
await ws.send(api.condition_search.condition_search_realtime(seq="1"))
await ws.listen()

검증 상태: 실서버(api.kiwoom.com) 대상으로 LOGIN 핸드셰이크 · PING 프레임 · REG 등록 응답까지 확인했습니다. 다만 REAL 프레임의 항목 필드명(item/values)은 장 마감 중이라 아직 미확정입니다. 장중 이상 동작을 만나면 이슈로 알려주세요. 직접 확인하려면 python tests/integration_ws_smoke.py --prod 를 돌리면 됩니다.

연속 조회 (페이지네이션)

데이터가 많은 API는 한 번에 모든 데이터를 반환하지 않습니다. 응답 헤더의 cont_yn이 "Y"이면 다음 페이지가 있다는 뜻입니다.

# 방법 1: 수동 연속 조회
result = api.account.filled_orders()
# result에 cont_yn="Y"와 next_key가 있으면 다음 페이지 조회
next_result = api.account.filled_orders(cont_yn="Y", next_key=result["next_key"])

# 방법 2: 자동 전체 조회 (모든 페이지를 한번에)
from kiwoom_rest_api.base import BaseClient
all_data = api._client.request_all(
    "/api/dostk/acnt", "ka10076",
    data_key="filled_list",  # 응답에서 리스트 데이터의 키 이름
)

에러 처리

from kiwoom_rest_api.base import KiwoomAPIError

try:
    result = api.order.buy_order(stk_cd="005930", ord_qty=10, ord_uv=70000)
except KiwoomAPIError as e:
    print(f"에러 코드: {e.code}")
    print(f"에러 메시지: {e.message}")
    print(f"전체 응답: {e.response}")

요청 제한 (Rate Limit)

키움 REST API는 TR(api_id)별로 독립적인 호출 제한을 둡니다. 실측 결과는 다음과 같습니다.

이에 맞춰 라이브러리는 기본적으로 TR별 토큰 버킷 Rate Limiter(1 req/s, 버스트 2) 를 적용하고, 그래도 429가 발생하면 자동으로 백오프 후 재시도합니다. 별도 설정 없이도 안전하게 동작합니다.

# 기본값: TR당 1 req/s, 버스트 2, 429 자동 재시도
api = KiwoomAPI(app_key="...", app_secret="...")

# 직접 조정 (예: TR당 2 req/s, 버스트 3, 재시도 5회)
api = KiwoomAPI(app_key="...", app_secret="...",
                rate_limit=2.0, rate_burst=3, max_retries=5)

# 클라이언트 측 스로틀 비활성화 (직접 제어할 때)
api = KiwoomAPI(app_key="...", app_secret="...", rate_limit=None)

제한이 TR별이라, 서로 다른 TR을 섞어 호출하면 합산 처리량은 더 높습니다. 반대로 같은 TR을 반복(연속조회 루프 등)할 때는 1 req/s에 수렴합니다 — 이 경우 request_all()을 쓰면 페이지네이션을 안전하게 자동 처리합니다.

자주 묻는 질문 (FAQ)

키움 앱키(appkey)와 시크릿키는 어떻게 발급받나요?

키움 REST API 포털에 로그인한 뒤 API 사용신청 메뉴에서 신청하면 appkey와 secretkey가 발급됩니다. 발급받은 키는 .env에 보관하고 코드에 직접 하드코딩하지 마세요. (.env.example 참고)

모의투자에서 실전투자로 어떻게 전환하나요?

KiwoomAPI 생성 시 is_mock 값만 바꾸면 됩니다. is_mock=True(모의투자) → is_mock=False(실전투자). 서버 URL은 라이브러리가 자동으로 전환합니다. 실전 전환 전 반드시 모의투자로 충분히 검증하세요.

api = KiwoomAPI(app_key="...", app_secret="...", is_mock=False)  # 실전투자

접근토큰(access token)이 만료되면 어떻게 하나요?

할 일이 없습니다. 토큰은 첫 호출에서 발급되고, 만료 60초 전에 선제 재발급되며, 그래도 인증 실패가 오면 재발급 후 한 번 더 시도합니다. (키움은 만료 토큰에 HTTP 401이 아니라 200 + return_code 3을 돌려주는데, 양쪽 다 인식합니다 — 실서버 확인 완료.) 갱신 시점을 바꾸려면 KiwoomAPI(..., expiry_margin=300)처럼 조절하세요.

여러 프로세스가 토큰을 공유해야 한다면 TokenProvider 프로토콜(get_valid_token() / refresh_token())을 구현해 넘기면 Redis 등 외부 캐시를 쓸 수 있습니다.

Rate limit(호출 제한) 에러가 발생합니다.

내장 TR별 토큰 버킷 Rate Limiter가 호출 빈도를 자동 조절하고 429 발생 시 재시도까지 처리합니다(실측 기준 TR당 1 req/s, 버스트 2). 그래도 제한에 걸린다면 다중 프로세스/스레드에서 같은 TR을 동시 호출 중인지 확인하고, 연속조회는 request_all()로 한 번에 처리하세요. 자세한 내용은 요청 제한 (Rate Limit)을 참고하세요.

조건검색(실시간)은 어떻게 사용하나요?

api.condition_search로 조건식 목록 조회·검색·실시간 등록/해제를 지원합니다. 실시간 조건검색은 WebSocket 기반으로 동작합니다. (지원 API 목록 참고)

Windows가 아닌 macOS/Linux에서도 되나요?

네. REST/WebSocket 기반이라 OCX·COM이 필요 없어 macOS·Linux·서버(헤드리스) 환경에서 모두 동작합니다.

pandas DataFrame으로 바로 받을 수 있나요?

to_dataframe(result) 한 줄이면 됩니다. 엔드포인트마다 다른 페이로드 키를 자동으로 찾고, "+70000" 같은 문자열도 숫자로 바꿔줍니다. 응답을 숫자·DataFrame으로 받기와 examples/pandas_usage.py를 참고하세요.

asyncio를 지원하나요?

네. AsyncKiwoomAPI가 KiwoomAPI와 같은 엔드포인트를 제공합니다. asyncio 사용법을 참고하세요.

환경 설정

지원 API 목록

인증

api.login()      # 접근토큰 발급 (au10001)
api.logout()     # 접근토큰 폐기 (au10002)

페이지네이션 (연속조회)

# 단일 조회
result = api.stock_info.basic_stock_info(stk_cd="005930")

# 연속 조회 (다음 페이지)
result = api.account.filled_orders(cont_yn="Y", next_key="다음키값")

계좌 (api.account) - 33개

종목정보 (api.stock_info) - 31개

시세 (api.market) - 25개

주문 (api.order) - 8개

신용주문 (api.credit_order) - 4개

차트 (api.chart) - 21개

순위정보 (api.ranking) - 23개

업종 (api.sector) - 6개

기관/외국인 (api.foreign_institution) - 4개

공매도 (api.short_selling) - 1개

대차거래 (api.slb) - 4개

테마 (api.theme) - 2개

조건검색 (api.condition_search) - 4개 (WebSocket)

ELW (api.elw) - 11개

ETF (api.etf) - 9개

실시간시세 (api.create_websocket()) - 19종

참고

• 공식 API 가이드: https://openapi.kiwoom.com/guide/apiguide
• 모의투자는 KRX만 지원됩니다.
• 모든 API 이름은 키움증권 공식 가이드 기준입니다.

라이선스

MIT

⭐ 도움이 되셨다면

이 라이브러리가 유용했다면 우측 상단 ⭐ Star 를 눌러주세요. 검색·추천 노출이 올라가 더 많은 개발자가 찾을 수 있습니다.

• 🐛 버그·질문 → Issues
• 🔧 개선 → PR 환영 (CONTRIBUTING)
• 📈 새 엔드포인트·기능 업데이트 소식을 받으려면 팔로우

관련 프로젝트 — 한국 주식 퀀트 스택

이 라이브러리는 제가 오픈소스로 공개하는 한국 주식 퀀트 스택의 일부입니다. 시세·펀더멘탈·뉴스 수집부터 데이터 파이프라인, 알파 리서치까지 이어집니다.

만든 사람

채영환 (Younghwan Chae) · GitHub @younghwan91 · LinkedIn

전체 오픈소스 퀀트 스택은 프로필에서 한눈에 볼 수 있습니다.