Metadata-Version: 2.4
Name: kis-trader
Version: 0.4.0
Summary: Typed Python client for the Korea Investment & Securities (KIS) Open API.
Project-URL: Homepage, https://seokhoonj.github.io/kis-trader/
Project-URL: Documentation, https://seokhoonj.github.io/kis-trader/
Project-URL: Repository, https://github.com/seokhoonj/kis-trader
Project-URL: Changelog, https://github.com/seokhoonj/kis-trader/blob/main/CHANGELOG.md
Author-email: Seokhoon Joo <seokhoonj@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: algorithmic-trading,api-client,brokerage,finance,kis,korea-investment,korea-investment-securities,koreainvestment,kosdaq,kospi,mcp,quant,stocks,trading,websocket,한국투자증권,한투
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cryptography>=42
Requires-Dist: requests>=2.31
Requires-Dist: websockets>=12
Provides-Extra: dev
Requires-Dist: mcp>=2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=2; extra == 'mcp'
Description-Content-Type: text/markdown

# kis-trader

[![check](https://github.com/seokhoonj/kis-trader/actions/workflows/check.yml/badge.svg)](https://github.com/seokhoonj/kis-trader/actions/workflows/check.yml)
[![PyPI](https://img.shields.io/pypi/v/kis-trader)](https://pypi.org/project/kis-trader/)
[![Python](https://img.shields.io/pypi/pyversions/kis-trader)](https://pypi.org/project/kis-trader/)
[![License](https://img.shields.io/pypi/l/kis-trader)](https://github.com/seokhoonj/kis-trader/blob/main/LICENSE)

**한국어** | [English](README.en.md)

한국투자증권(한투) **KIS Open API**를 타입을 갖춘 깔끔한 파이썬 API로 감싼 비공식 클라이언트입니다.

- **넓은 범위** — 국내·해외 주식·지수·ETF·ETN·ELW·선물옵션·채권의 시세·재무·수급, 계좌 잔고·손익, 순위·조건검색, 시장·일정, 퇴직연금.
- **주문** — 매수·매도·정정·취소, 신용·예약·TWAP 분할.
- **안전 코어** — 같은 주문의 중복 전송 차단, 전송 전 리스크 한도로 주문 실수 방지, 타임아웃이 나면 재전송이 아니라 reconcile로 재확인 — 모두 기본으로 켜져 있고, 신용거래는 기본 차단.
- **실시간** — 시세·호가·체결통보를 WebSocket으로 수신.
- **세 가지 인터페이스** — 파이썬 API · 터미널 명령 `kis` · AI 에이전트용 MCP 서버/스킬.

## 1. 설치

```bash
pip install kis-trader
```

파이썬 3.11 이상이 필요합니다.

Claude Desktop 같은 AI 에이전트에서 MCP 서버로 쓰려면 `mcp` 옵션을 함께 설치합니다:

```bash
pip install 'kis-trader[mcp]'
```

## 2. 빠른 시작

```python
from kis_trader import KISClient

kis = KISClient(app_key="…", app_secret="…", account="12345678-01")

kis.domestic.stock("005930").quote()                 # 삼성전자 현재가
kis.overseas.stock("AAPL").quote()                   # 애플 (거래소 자동 판별)
kis.domestic.ranking.by_change(direction="gainers")  # 오늘 상승률 순위
```

터미널에서 `kis config` 를 실행하면 앱키와 계좌를 대화형으로 입력받아 저장합니다. 환경변수나
`KISConfig(...).save()` 로 저장할 수도 있으며, 한 번 저장해 두면 이후 `KISClient()` 를 인자 없이
열 수 있습니다. 실전 계좌와 모의투자 계좌를 모두 지원하므로, 먼저 모의투자로 주문 흐름을 확인한 뒤
실전으로 옮겨도 됩니다. 발급과 저장은 [자격증명과 프로필](https://seokhoonj.github.io/kis-trader/configuration.html)
문서를 참고하세요.

## 3. 구조

`KISClient` 아래로 자산군과 주문이 네임스페이스로 나뉩니다.

```python
kis.domestic   # 국내: 주식·지수·ETF·ELW·선물옵션·채권·계좌·순위·시장·일정
kis.overseas   # 해외: 주식·지수·선물옵션·계좌·순위
kis.account    # 계좌 조회 (상품코드 자동 분기; IRP는 .pension 퇴직연금 조회)
kis.orders     # 접수한 주문의 조회(미체결)·확인·정정·취소
```

종목과 계약은 핸들로 잡으면 시세 조회부터 주문까지 그대로 이어집니다.

```python
kis.domestic.stock("005930")     # 국내 주식 -- 현재가·차트·호가·매수·매도
kis.overseas.stock("AAPL")       # 해외 주식 -- 거래소 자동 판별
kis.domestic.futures("101W09")   # 지수선물
kis.domestic.option("201W09")    # 지수옵션
```

## 4. 주문

```python
r = kis.domestic.stock("005930").buy(quantity=10, limit_price=70000)  # 10주 매수
kis.orders.reconcile(r.client_order_id)   # 실제 접수 여부를 증권사에 재확인
kis.orders.cancel(r.client_order_id)      # 취소
```

주문은 되돌릴 수 없습니다. 중복 주문을 막는 안전장치가 기본으로 동작합니다(신용거래는 기본
차단). 자세한 규칙은 [주문 문서](https://seokhoonj.github.io/kis-trader/orders.html)에 있습니다.

## 5. 명령줄 (`kis`)

설치하면 `kis` 터미널 명령이 함께 설치됩니다. 파이썬 코드를 쓰지 않고도 터미널에서 바로 조회하고
주문할 수 있습니다. 주문은 `--execute` 를 붙이기 전까지는 실제로 전송되지 않습니다(기본이 dry-run).

```bash
kis config                      # 자격증명을 대화형으로 입력받아 프로필에 저장
kis stock quote 005930
kis search 삼성전자
kis ranking change --direction gainers
kis account balance
kis order buy 005930 10 --limit-price 70000
kis order buy 005930 10 --limit-price 70000 --execute paper --yes
```

채권·선물·옵션·해외·예약주문·TWAP 등 전체 명령과 옵션은
[명령줄 문서](https://seokhoonj.github.io/kis-trader/cli.html)를 보세요.

## 6. AI 코딩 에이전트에서 사용

Claude Code·Codex 같은 AI 도구로 계좌를 다루려면 `plugins/kis-trader/skills/kis-trader/` 스킬을 씁니다.
[Claude 스킬](https://seokhoonj.github.io/kis-trader/claude-skill.html) ·
[Codex 스킬](https://seokhoonj.github.io/kis-trader/codex-skill.html) 문서를 참고하세요.

MCP 호환 에이전트(Claude Desktop 등)에서는 `kis_trader.mcp` 서버(`pip install 'kis-trader[mcp]'` 후
`kis-mcp`)로 계좌 조회·주문 미리보기 도구를 쓸 수 있습니다(실주문 전송은 노출하지 않습니다).
[MCP 서버](https://seokhoonj.github.io/kis-trader/mcp.html) 문서를 참고하세요.

## 7. 문서

전체 문서는 **<https://seokhoonj.github.io/kis-trader/>** 에 있습니다(소스: `docs/`).

| 파트 | 장 |
|------|----|
| **시작하기** | [빠른 시작](https://seokhoonj.github.io/kis-trader/quickstart.html) · [앱키 발급](https://seokhoonj.github.io/kis-trader/appkey.html) · [자격증명과 프로필](https://seokhoonj.github.io/kis-trader/configuration.html) |
| **국내 주식** | [시세](https://seokhoonj.github.io/kis-trader/quotes.html) · [재무·실적](https://seokhoonj.github.io/kis-trader/financials.html) · [종목 수급](https://seokhoonj.github.io/kis-trader/flows.html) · [계좌·손익](https://seokhoonj.github.io/kis-trader/account.html) · [주문](https://seokhoonj.github.io/kis-trader/orders.html) |
| **시장·검색** | [순위·조건검색](https://seokhoonj.github.io/kis-trader/screening.html) · [시장·지수](https://seokhoonj.github.io/kis-trader/market.html) · [기업행위·일정](https://seokhoonj.github.io/kis-trader/corporate-actions.html) |
| **해외·연금** | [해외주식](https://seokhoonj.github.io/kis-trader/overseas.html) · [퇴직연금](https://seokhoonj.github.io/kis-trader/pension.html) |
| **다른 상품** | [ETF·ETN](https://seokhoonj.github.io/kis-trader/etf.html) · [ELW](https://seokhoonj.github.io/kis-trader/elw.html) · [선물·옵션](https://seokhoonj.github.io/kis-trader/derivatives.html) · [채권](https://seokhoonj.github.io/kis-trader/bonds.html) |
| **명령줄·에이전트** | [Command Line](https://seokhoonj.github.io/kis-trader/cli.html) · [Claude Skill](https://seokhoonj.github.io/kis-trader/claude-skill.html) · [Codex Skill](https://seokhoonj.github.io/kis-trader/codex-skill.html) · [MCP Server](https://seokhoonj.github.io/kis-trader/mcp.html) |
| **참고** | [실시간(WebSocket)](https://seokhoonj.github.io/kis-trader/realtime.html) · [한계·미구현](https://seokhoonj.github.io/kis-trader/limits.html) |

각 메서드의 인자와 반환값은 파이썬 `help()` 로 바로 확인할 수 있습니다 (예: `help(kis.domestic.stock)`).

## 8. 라이선스

[MIT](LICENSE)

<!-- mcp-name: io.github.seokhoonj/kis-trader -->

