kis_utils 0.1.0

Korea Investment & Securities API Utils

KIS Utils

한국투자증권 API를 파이썬에서 쉽고 간편하게 사용할 수 있도록 도와주는 유틸리티 모듈로 CLI 인터페이스를 제공합니다. 접근 토큰 관리, 시세 조회, 잔고 확인 및 주문 기능을 간결한 인터페이스로 제공합니다.

비교적 간편한 유틸리티 라이브러리로 사용하거나 CLI로 사용이 가능합니다

🚀 시작하기

1. 환경 설정

2. .env 파일 설정

프로젝트 루트 디렉토리에 .env.example 파일을 복사하여 .env 파일을 생성하고 다음과 같이 환경 변수를 설정합니다.

# 실행 환경 ("실전투자" 또는 "모의투자")
KIS_ENVIRONMENT="모의투자"

# 실전투자 정보
KIS_APP_KEY="YOUR_PROD_APP_KEY"
KIS_APP_SECRET="YOUR_PROD_APP_SECRET"
KIS_ACCOUNT="YOUR_ACCOUNT_NUMBER"
KIS_ACCOUNT_PROD="01"

# 모의투자 정보 (KIS_ENVIRONMENT="모의투자"인 경우 필수)
KIS_APP_KEY_VTS="YOUR_VTS_APP_KEY"
KIS_APP_SECRET_VTS="YOUR_VTS_APP_SECRET"
KIS_ACCOUNT_VTS="YOUR_VTS_ACCOUNT_NUMBER"
KIS_ACCOUNT_PROD_VTS="01"

CLI 사용법

가장 간편하게 uv 명령어를 사용하여 실행할 수 있습니다. (또는 python -m kis_utils 사용 가능)

# 현재가 조회 (기본 JSON 출력)
uv run kis price 005930

# 사람이 읽기 좋은 포맷으로 조회
uv run kis price 005930 --pretty

# 계좌 잔고 확인
uv run kis balance --pretty

# 주식 주문 (삼성전자 1주 시장가 매수)
uv run kis order 005930 -t buy -q 1 -p 0 -d 03

주요 명령어

• token: 접근 토큰 신규 발급
• price <종목코드>: 현재가 정보 조회
• daily <종목코드>: 일/주/월 봉 데이터 조회
• balance: 계좌 잔고 및 보유 종목 조회
• history: 주문 및 체결 내역 조회
• order: 주식 주문 (매수/매도)
• buyable <종목코드>: 매수 가능 수량 조회

모든 명령어 뒤에 --pretty를 붙이면 한글 라벨이 포함된 가독성 좋은 화면을 볼 수 있습니다.

기본 사용법

1. 접근 토큰 발급

import kis_utils as kis

# 토큰 발급 (자동으로 파일에 저장 및 갱신됨)
access_token = kis.token()

2. 주식 시세 및 데이터 조회

현재가 조회

# 삼성전자 현재가 조회
df = kis.price("005930")
if not price_df.empty:
    current_price = int(price_df['stck_prpr'].iloc[0])
    print(f"현재가: {current_price:,}원")

일봉 데이터 조회

from datetime import datetime, timedelta

today = datetime.now()
start_date = (today - timedelta(days=30)).strftime("%Y%m%d")
end_date = today.strftime("%Y%m%d")

# 최근 30일 일봉 데이터
daily_data = kis.daily("005930")

# 주봉 데이터
weekly_data = kis.daily("005930", period="W")

3. 계좌 및 주문 관리

계좌 잔고 조회

balance = kis.balance()

# 예수금 확인
deposit = int(balance['output2'][0]['dnca_tot_amt'])

# 보유 종목 확인
for stock in balance['output1']:
    print(f"종목명: {stock['prdt_name']}, 보유수량: {stock['hldg_qty']}")

주문 내역 조회

# 최근 7일간 주문 내역 조회
history = kis.order_history(start_date, end_date)

주식 주문

# 삼성전자 1주 시장가 매수
result = kis.buy(
    stock_code="005930",
    quantity=1,
    price=0,               # 시장가인 경우 0
    order_division="03"    # 01: 지정가, 03: 시장가
)

# 삼성전자 1주 지정가 매도
result = kis.sell(
    stock_code="005930",
    quantity=1,
    price=70000,
    order_division="01"
)

📝 참고 사항

• 토큰 자동 관리: 발급된 토큰은 .access_token 파일에 자동 저장되며, 만료 전 호출 시 기존 토큰을 재사용하거나 필요시 자동 갱신합니다.
• 오류 처리: API 호출 실패 시 관련 에러 메시지를 출력하며, 네트워크 상태나 앱 키 설정을 확인해야 합니다.
• 주문 주의: place_order 함수는 실제 거래를 발생시키므로, 충분한 테스트 후에 실전 투자에 사용하시기 바랍니다.

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.