# kiwoompy

키움증권 REST API를 Python에서 편하게 쓰기 위한 라이브러리입니다.

[![PyPI](https://img.shields.io/pypi/v/kiwoompy)](https://pypi.org/project/kiwoompy/)
[![Python](https://img.shields.io/pypi/pyversions/kiwoompy)](https://pypi.org/project/kiwoompy/)
[![Docs](https://img.shields.io/badge/docs-meonji--gogo.github.io-blue)](https://meonji-gogo.github.io/kiwoompy/)
[![License](https://img.shields.io/pypi/l/kiwoompy)](LICENSE)

## 설치

```bash
pip install kiwoompy
```

uv 사용 시:

```bash
uv add kiwoompy
```

Python 3.12 이상이 필요합니다.

## 사전 준비

[키움증권 OpenAPI](https://openapi.kiwoom.com)에서 앱을 등록하고 **App Key** / **App Secret**을 발급받아야 합니다.

> **주의** — App Key와 App Secret은 코드에 직접 넣지 마세요. 환경 변수나 시크릿 매니저로 관리하세요.

## 빠른 시작

```python
from kiwoompy import KiwoomClient

client = KiwoomClient(
    env="demo",               # "demo"(모의투자) / "real"(실계좌)
    appkey="YOUR_APP_KEY",
    secretkey="YOUR_APP_SECRET",
)

# 계좌 잔고 조회
balance = client.query.get_account_balance()
print(balance.tot_evlt_amt)   # 총평가금액

for item in balance.holdings:
    print(item.stk_nm, item.evlt_amt)
```

```python
# 시장가 매수
result = client.order.buy("005930", quantity="1", trade_type="market")
print(result.ord_no)

# 지정가 매도
client.order.sell("005930", quantity="1", trade_type="limit", price="75000")
```

context manager도 지원합니다.

```python
with KiwoomClient(env="demo", appkey="...", secretkey="...") as client:
    deposit = client.query.get_deposit(query_type="normal")
    print(deposit.entr)   # 예수금
```

## 기능

- **OAuth2 인증** — 접근토큰 발급·만료 자동 관리
- **환경 분리** — 모의투자 / 실계좌 한 줄로 전환
- **유량 제어** — 모의 2건/초, 실전 20건/초 자동 적용
- **자동 재시도** — 네트워크 오류·5xx 지수 백오프 재시도 (최대 3회)
- **입력값 보완** — 계좌번호 상품코드 누락 시 자동 보완
- **타입 힌트** — IDE 자동완성·정적 분석 지원

## 에러 처리

```python
from kiwoompy import KiwoomAuthError, KiwoomApiError

try:
    client = KiwoomClient(env="demo", appkey="wrong", secretkey="wrong")
except KiwoomAuthError as e:
    print(f"인증 실패: {e}")
except KiwoomApiError as e:
    print(f"API 오류: {e}")
```

| 예외 | 발생 조건 |
|------|-----------|
| `KiwoomAuthError` | 잘못된 키, 토큰 미발급 상태에서 API 호출 |
| `KiwoomApiError` | 네트워크 오류, 5xx 서버 오류, 응답 파싱 실패 |

## 문서

전체 사용법과 API 레퍼런스는 문서 사이트를 참고해 주세요.

👉 **https://meonji-gogo.github.io/kiwoompy**

## 키움증권 REST API 공지 알리미

키움증권 REST API 공지사항·변경 사항을 텔레그램으로 받아볼 수 있습니다.

👉 **https://t.me/+2do4kWIhBmg3OTM1**

## 라이선스

MIT
