python-kis

파이썬 한국투자증권 REST 기반 Trading API 라이브러리

These details have not been verified by PyPI

Project links

Project description

header

1. 파이썬용 한국투자증권 API 소개 ✨

한국투자증권의 트레이딩 OPEN API 서비스를 파이썬 환경에서 사용할 수 있도록 만든 강력한 커뮤니티 라이브러리입니다.

2.0.0 버전 이전의 라이브러리는 여기, 문서는 1, 2, 3에서 확인할 수 있습니다.

1.1. 라이브러리 특징

📐 모든 객체에 대한 Type hint

모든 함수와 클래스에 대해 추상화 및 Typing을 적용하여, 파이썬의 동적 타이핑을 보완합니다.
IDE의 자동완성을 100% 활용할 수 있으며, 공식 문서 없이 정확하고 버그 없는 개발이 가능합니다.

🔗 복구 가능한 웹소켓 클라이언트

실시간 시세, 호가, 체결 등의 실시간 데이터를 받아오는 과정에서 네트워크 문제 등으로 인해 연결이 끊겼을 때, 완벽히 복구할 수 있도록 만들어졌습니다.
재연결 이전에 등록된 조회도 자동으로 다시 등록하여 유실을 방지합니다.
한국투자증권의 웹소켓 조회 시스템을 파이썬의 메모리 관리 시스템과 완벽히 통합하여, GC에 의해 이벤트 구독이 관리됩니다.

🖋️ 표준 영어 네이밍

한국투자증권의 API의 경우, 한글 발음이나 비표준 약어를 사용하는 경우가 많습니다.
이 라이브러리는 모든 객체에 대해 표준 영어 네이밍을 적용하여, 이해하기 쉽도록 만들었습니다.

2. 사용 설명 ⚙️

OpenAPI 서비스 신청 방법

한국투자증권 계좌와 아이디가 필요합니다. KIS 트레이딩 서비스는 KIS Developers 서비스를 통해 신청 할 수 있습니다.

서비스를 신청이 완료되면, 아래와 같이 앱 키를 발급 받을 수 있습니다.

2.1. 라이브러리 설치 📦

라이브러리는 파이썬 3.11을 기준으로 작성되었습니다.

pip install python-kis

사용된 모듈 보기

requests>=2.32.3
websocket-client>=1.8.0
cryptography>=43.0.0
colorlog>=6.8.2

2.2. 라이브러리 사용 📚

2.2.1. PyKis 객체 생성

시크릿 키를 파일로 관리하는 방법 (권장)

먼저 시크릿 키를 파일로 저장합니다.

 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 접속 토큰 자동 저장
)

2.2.2. 시세 조회

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
)

2.2.3. 잔고 조회

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
)

2.2.4. 매도/매수 주문

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()

2.2.4. 실시간 체결가 조회

국내주식 및 해외주식의 실시간 체결가 조회는 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

3. 튜토리얼 목록 📖

4. Changelog ✨

ver 2.0.3

KisIntegrationBalance에서 해외주식 잔고수량이 0으로 표시됨 버그를 수정했습니다.

ver 2.0.2

KisBalance, KisChart 등 __iter__ 메서드의 반환 타입이 누락되어있는 버그를 수정했습니다.
주문 수량을 입력할 때 Decimal 타입 이외의 int, float 타입을 입력할 수 있도록 개선했습니다.

ver 2.0.1

초기 웹소켓 이벤트 구독시 클라이언트 접속 후 구독을 요청하는 코드에서 _connected_event가 set 되어있지 않아, 요청이 무시되는 버그를 수정했습니다.

ver 2.0.0

라이브러리가 완전히 새롭게 변경되었습니다.
모든 객체에 대한 추상화 및 네이밍이 변경되었습니다.
한국투자증권의 국내, 해외 API 구분 없이 동일한 인터페이스로 사용할 수 있습니다.
실시간 시세 조회는 새로운 이벤트 시스템으로 변경되었습니다.
계좌 및 상품 Scope 활용이 극대화되었습니다.

ver 1.0.6

상품기본조회가 추가되었습니다.
환경 변수를 분리하였습니다. 각각의 파일에 나뉘어있던 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()를 호출하는 문제를 해결하였습니다.

ver 1.0.5

RTClient에서 웹소켓 연결이 끊어졌을 때, 이벤트 처리가 잘못되는 버그를 수정하였습니다.
RTClient에서 재연결시 실시간 조회가 복구되지 않는 버그를 수정하였습니다.
휴장일 조회가 추가되었습니다.
해외 주식 주문이 추가되었습니다.
해외 미체결 조회가 추가되었습니다.

ver 1.0.4

주식잔고조회_실현손익 조회가 추가되었습니다.
실시간 해제요청이 정상적으로 되지 않습니다 버그를 수정하였습니다.

ver 1.0.3

RTClient 웹소켓 보안강화를 위한 개선 안내의 내용에 따라, 앱키 대신 웹소켓 접속키를 발급하여 사용하도록 변경되었습니다.

ver 1.0.2

API 초당 요청 제한을 넘어버리는 버그를 수정하였습니다.
period_price 응답 데이터의 stck_fcam값 float으로 변경하였습니다.
utils.KRXMarketOpen 공휴일 데이터가 1개인 경우 오류 발생하는 버그 수정하였습니다.

License

MIT

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

2.0.3

Aug 28, 2024

2.0.2

Aug 8, 2024

2.0.1

Aug 6, 2024

2.0.0

Aug 5, 2024

1.0.6

Jul 31, 2023

1.0.5

Jun 2, 2023

1.0.4

Mar 20, 2023

1.0.3

Jan 28, 2023

1.0.2

Oct 9, 2022

1.0.1

Oct 6, 2022

1.0.0

Oct 6, 2022

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

python_kis-2.0.3-py3-none-any.whl (477.5 kB view hashes)

Uploaded Aug 28, 2024 Python 3

Hashes for python_kis-2.0.3-py3-none-any.whl

Hashes for python_kis-2.0.3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`20a8db0617483a6c47f91a4a03c9163d65541449d7863f4b71e74b966ea54718`
MD5	`3247b5e22345d6f9aa6ceea44a74c274`
BLAKE2b-256	`98d498aaecaa0233fb840d058a269f850f8d604c3b85baa349aa4c53409f33c1`