kis-trader

한국어 | English

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

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

1. 설치

pip install kis-trader

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

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

pip install 'kis-trader[mcp]'

2. 빠른 시작

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() 를 인자 없이 열 수 있습니다. 실전 계좌와 모의투자 계좌를 모두 지원하므로, 먼저 모의투자로 주문 흐름을 확인한 뒤 실전으로 옮겨도 됩니다. 발급과 저장은 자격증명과 프로필 문서를 참고하세요.

3. 구조

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

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

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

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

4. 주문

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)      # 취소

주문은 되돌릴 수 없습니다. 중복 주문을 막는 안전장치가 기본으로 동작합니다(신용거래는 기본 차단). 자세한 규칙은 주문 문서에 있습니다.

5. 명령줄 (kis)

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

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 등 전체 명령과 옵션은 명령줄 문서를 보세요.

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

Claude Code·Codex 같은 AI 도구로 계좌를 다루려면 plugins/kis-trader/skills/kis-trader/ 스킬을 씁니다. Claude 스킬 · Codex 스킬 문서를 참고하세요.

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

7. 문서

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

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

8. 라이선스

MIT