한국투자증권의 트레이딩 OPEN API 서비스를 파이썬 환경에서 사용할 수 있도록 만든 강력한 커뮤니티 라이브러리입니다.
2.0.0 버전 이전의 라이브러리는 여기, 문서는 1, 2, 3에서 확인할 수 있습니다.
📐 모든 객체에 대한 Type hint
- 모든 함수와 클래스에 대해 추상화 및 Typing을 적용하여, 파이썬의 동적 타이핑을 보완합니다.
- IDE의 자동완성을 100% 활용할 수 있으며, 공식 문서 없이 정확하고 버그 없는 개발이 가능합니다.
🔗 복구 가능한 웹소켓 클라이언트
- 실시간 시세, 호가, 체결 등의 실시간 데이터를 받아오는 과정에서 네트워크 문제 등으로 인해 연결이 끊겼을 때, 완벽히 복구할 수 있도록 만들어졌습니다.
- 재연결 이전에 등록된 조회도 자동으로 다시 등록하여 유실을 방지합니다.
- 한국투자증권의 웹소켓 조회 시스템을 파이썬의 메모리 관리 시스템과 완벽히 통합하여, GC에 의해 이벤트 구독이 관리됩니다.
🖋️ 표준 영어 네이밍
- 한국투자증권의 API의 경우, 한글 발음이나 비표준 약어를 사용하는 경우가 많습니다.
- 이 라이브러리는 모든 객체에 대해 표준 영어 네이밍을 적용하여, 이해하기 쉽도록 만들었습니다.
OpenAPI 서비스 신청 방법
- 한국투자증권 계좌와 아이디가 필요합니다. KIS 트레이딩 서비스는 KIS Developers 서비스를 통해 신청 할 수 있습니다.
- 서비스를 신청이 완료되면, 아래와 같이 앱 키를 발급 받을 수 있습니다.
라이브러리는 파이썬 3.11을 기준으로 작성되었습니다.
pip install python-kis사용된 모듈 보기
requests>=2.32.3
websocket-client>=1.8.0
cryptography>=43.0.0
colorlog>=6.8.2
-
시크릿 키를 파일로 관리하는 방법 (권장)
먼저 시크릿 키를 파일로 저장합니다.
from pykis import KisAuth auth = KisAuth( # HTS 로그인 ID 예) soju06 id="YOUR_HTS_ID", # 앱 키 예) Pa0knAM6JLAjIa93Miajz7ykJIXXXXXXXXXX appkey="YOUR_APP_KEY", # 앱 시크릿 키 예) V9J3YGPE5q2ZRG5EgqnLHn7XqbJjzwXcNpvY . . . secretkey="YOUR_APP_SECRET", # 앱 키와 연결된 계좌번호 예) 00000000-01 account="00000000-01", # 모의투자 여부 virtual=False, ) # 안전한 경로에 시크릿 키를 파일로 저장합니다. auth.save("secret.json")
그 후, 저장된 시크릿 키를 사용하여 PyKis 객체를 생성합니다.
from pykis import PyKis, KisAuth # 실전투자용 PyKis 객체를 생성합니다. kis = PyKis("secret.json", keep_token=True) kis = PyKis(KisAuth.load("secret.json"), keep_token=True) # 모의투자용 PyKis 객체를 생성합니다. kis = PyKis("secret.json", "virtual_secret.json", keep_token=True) kis = PyKis(KisAuth.load("secret.json"), KisAuth.load("virtual_secret.json"), keep_token=True)
-
시크릿 키를 직접 입력하는 방법
from pykis import PyKis # 실전투자용 한국투자증권 API를 생성합니다. kis = PyKis( id="soju06", # HTS 로그인 ID account="00000000-01", # 계좌번호 appkey="PSED321z...", # AppKey 36자리 secretkey="RR0sFMVB...", # SecretKey 180자리 keep_token=True, # API 접속 토큰 자동 저장 ) # 모의투자용 한국투자증권 API를 생성합니다. kis = PyKis( id="soju06", # HTS 로그인 ID account="00000000-01", # 모의투자 계좌번호 appkey="PSED321z...", # 실전투자 AppKey 36자리 secretkey="RR0sFMVB...", # 실전투자 SecretKey 180자리 virtual_id="soju06", # 모의투자 HTS 로그인 ID virtual_appkey="PSED321z...", # 모의투자 AppKey 36자리 virtual_secretkey="RR0sFMVB...", # 모의투자 SecretKey 180자리 keep_token=True, # API 접속 토큰 자동 저장 )
stock.quote() 함수를 이용하여 국내주식 및 해외주식의 시세를 조회할 수 있습니다.
from pykis import KisQuote
# 엔비디아의 상품 객체를 가져옵니다.
stock = kis.stock("NVDA")
quote: KisQuote = stock.quote()
quote: KisQuote = stock.quote(extended=True) # 주간거래 시세
# PyKis의 모든 객체는 repr을 통해 주요 내용을 확인할 수 있습니다.
# 데이터를 확인하는 용도이므로 실제 프로퍼티 타입과 다를 수 있습니다.
print(quote)KisForeignQuote(
symbol='NVDA',
market='NASDAQ',
name='엔비디아',
sector_name='반도체 및 반도체장비',
volume=1506310,
amount=160791125,
market_cap=2593332000000,
indicator=KisForeignIndicator(
eps=1.71,
bps=2,
per=63.88,
pbr=54.65,
week52_high=140.76,
week52_low=39.2215,
week52_high_date='2024-06-20',
week52_low_date='2023-10-31'
),
open=109.21,
high=109.38,
low=104.37,
close=105.42,
change=-3.79,
unit=1,
tick=0.01,
risk='none',
halt=False,
overbought=False
)account.balance() 함수를 이용하여 예수금 및 보유 종목을 조회할 수 있습니다.
from pykis import KisBalance
# 주 계좌 객체를 가져옵니다.
account = kis.account()
balance: KisBalance = account.balance()
print(repr(balance)) # repr을 통해 객체의 주요 내용을 확인할 수 있습니다.KisIntegrationBalance(
account_number=KisAccountNumber('50113500-01'),
deposits={
'KRW': KisDomesticDeposit(account_number=KisAccountNumber('50113500-01'), currency='KRW', amount=2447692, exchange_rate=1),
'USD': KisForeignPresentDeposit(account_number=KisAccountNumber('50113500-01'), currency='USD', amount=0, exchange_rate=1384.6),
},
stocks=[
KisDomesticBalanceStock(account_number=KisAccountNumber('50113500-01'), market='KRX', symbol='000660', qty=14, price=192600, amount=2696400, profit=22900, profit_rate=0.856555077613615111277351786),
KisDomesticBalanceStock(account_number=KisAccountNumber('50113500-01'), market='KRX', symbol='039200', qty=118, price=39600, amount=4672800, profit=-199500, profit_rate=-4.094575457176282248630010467)
],
purchase_amount=7545800,
current_amount=7369200,
profit=-176600,
profit_rate=-2.340374778022211031302181346
)stock.order(), stock.buy(), stock.sell(), stock.modify(), stock.cancel() 함수를 이용하여 매수/매도 주문 및 정정/취소를 할 수 있습니다.
from pykis import KisOrder
# SK하이닉스 1주 시장가 매수 주문
order: KisOrder = hynix.buy(qty=1)
# SK하이닉스 1주 지정가 매수 주문
order: KisOrder = hynix.buy(price=194700, qty=1)
# SK하이닉스 전량 시장가 매도 주문
order: KisOrder = hynix.sell()
# SK하이닉스 전량 지정가 매도 주문
order: KisOrder = hynix.sell(price=194700)
print(order.pending) # 미체결 주문인지 여부
print(order.pending_order.pending_qty) # 미체결 수량
order: KisOrder = order.modify(price=195000) # 단가 정정
order: KisOrder = order.modify(qty=10) # 수량 정정
order.cancel() # 주문 취소
# 미체결 주문 전체 취소
for order in account.pending_orders():
order.cancel()국내주식 및 해외주식의 실시간 체결가 조회는 stock.on("price", callback) 함수를 이용하여 수신할 수 있습니다.
from pykis import KisRealtimePrice, KisSubscriptionEventArgs, KisWebsocketClient, PyKis
def on_price(sender: KisWebsocketClient, e: KisSubscriptionEventArgs[KisRealtimePrice]):
print(e.response)
ticket = hynix.on("price", on_price)
print(kis.websocket.subscriptions) # 현재 구독중인 이벤트 목록
input("Press Enter to exit...")
ticket.unsubscribe(){KisWebsocketTR(id='H0STCNT0', key='000660')}
Press Enter to exit...
[08/02 13:50:42] INFO: RTC Connected to real server
[08/02 13:50:42] INFO: RTC Restoring subscriptions... H0STCNT0.000660
[08/02 13:50:42] INFO: RTC Subscribed to H0STCNT0.000660
KisDomesticRealtimePrice(market='KRX', symbol='000660', time='2024-08-02T13:50:44+09:00', price=174900, change=-18400, volume=8919304, amount=1587870362300)
KisDomesticRealtimePrice(market='KRX', symbol='000660', time='2024-08-02T13:50:44+09:00', price=174800, change=-18500, volume=8919354, amount=1587879102300)
KisDomesticRealtimePrice(market='KRX', symbol='000660', time='2024-08-02T13:50:45+09:00', price=174800, change=-18500, volume=8919358, amount=1587879801500)
KisDomesticRealtimePrice(market='KRX', symbol='000660', time='2024-08-02T13:50:45+09:00', price=174900, change=-18400, volume=8920313, amount=1588046831000)
KisDomesticRealtimePrice(market='KRX', symbol='000660', time='2024-08-02T13:50:45+09:00', price=174800, change=-18500, volume=8920319, amount=1588047879800)
[08/02 13:50:48] INFO: RTC Unsubscribed from H0STCNT0.000660- HTTPSConnectionPool이 제대로 닫히지 않는 것 같습니다. fixed #58: session 추가 by @tasoo-oos
- Refector/decorator keeping function information
KisChartBar의 타이핑 문제를 해결했습니다.
- fix: SyntaxError: f-string: expecting '}' but got "}" 파이썬 3.11 이하에서 SyntaxError 오류가 발생하는 문제를 해결했습니다. by @tasoo-oos
- 해외주식 실시간 체결 이벤트 버그 수정 해외주식 실시간 체결 이벤트를 받을 수 없는 버그를 수정했습니다.
- 이벤트 티켓 암시적 구독 해지 경고 메시지 추가 이벤트 티켓이 GC에 의해 해지되었을 때 경고 메시지를 추가했습니다.
- 코드 리펙토링 기존
EMPTY,EMPTY_TYPE대신EllipsisType를 사용하도록 변경하고,Impl타입의 이름을Mixin으로 변경했습니다.
- 몇몇 종목의 주식 객체 quote, chart 동작 관련 질문 상품기본정보 조회 시세조회 가능 여부 확인 로직을 추가했습니다.
- order 객체를 분실했을 때, order 객체를 다시 가져올 수 있는 방법이 있을까요? 미체결 주문 객체에 KisOrder 프로토콜을 지원하도록 개선했습니다.
- 인증 토큰 만료되었을 때 발생하는 예외를 핸들링하여 재발급을 시도하도록 개선했습니다.
- krx 주식 002170 정보를 quote 로 가져올 때 발생하는 버그 국내주식 시세조회의 업종명이 없을때 발생하는 버그를 수정했습니다.
- KisIntegrationBalance에서 해외주식 잔고수량이 0으로 표시됨 버그를 수정했습니다.
KisBalance,KisChart등__iter__메서드의 반환 타입이 누락되어있는 버그를 수정했습니다.- 주문 수량을 입력할 때
Decimal타입 이외의int,float타입을 입력할 수 있도록 개선했습니다.
- 초기 웹소켓 이벤트 구독시 클라이언트 접속 후 구독을 요청하는 코드에서
_connected_event가 set 되어있지 않아, 요청이 무시되는 버그를 수정했습니다.
- 라이브러리가 완전히 새롭게 변경되었습니다.
- 모든 객체에 대한 추상화 및 네이밍이 변경되었습니다.
- 한국투자증권의 국내, 해외 API 구분 없이 동일한 인터페이스로 사용할 수 있습니다.
- 실시간 시세 조회는 새로운 이벤트 시스템으로 변경되었습니다.
- 계좌 및 상품 Scope 활용이 극대화되었습니다.
-
상품기본조회가 추가되었습니다.
-
환경 변수를 분리하였습니다. 각각의 파일에 나뉘어있던 Version, 접속 URL, API Rate Limit 등의 상수 데이터를
__env__.py로 옮겼습니다. -
예외구조 변경 기존 HTTP Error, RT_CD Error를 모두
ValueError로 처리하던 구조에서 각각의KisHTTPError,KisAPIError예외 객체로 나누었고,rt_cd,msg_cd등의 변수를 예외 객체에서 참조할 수 있도록 변경하였습니다. -
엑세스토큰 발급 Thread Safe 엑세스 토큰이 발급되어있지 않은 상태에서 멀티스레드로
KisAccessToken.ensure()함수를 호출하면 Thread Lock 되지 않고 다수가KisAccessToken.issue()를 호출하는 문제를 해결하였습니다.
-
RTClient에서 웹소켓 연결이 끊어졌을 때, 이벤트 처리가 잘못되는 버그를 수정하였습니다. -
RTClient에서 재연결시 실시간 조회가 복구되지 않는 버그를 수정하였습니다. -
휴장일 조회가 추가되었습니다.
-
해외 주식 주문이 추가되었습니다.
-
해외 미체결 조회가 추가되었습니다.
-
주식잔고조회_실현손익 조회가 추가되었습니다.
-
실시간 해제요청이 정상적으로 되지 않습니다 버그를 수정하였습니다.
RTClient웹소켓 보안강화를 위한 개선 안내의 내용에 따라, 앱키 대신 웹소켓 접속키를 발급하여 사용하도록 변경되었습니다.
- API 초당 요청 제한을 넘어버리는 버그를 수정하였습니다.
period_price응답 데이터의stck_fcam값float으로 변경하였습니다.utils.KRXMarketOpen공휴일 데이터가 1개인 경우 오류 발생하는 버그 수정하였습니다.