kis-trader

한국어 | English

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

• 넓은 범위 — 국내·해외 주식·지수·ETF·ETN·ELW·선물옵션·채권의 시세·재무·수급, 계좌 잔고·손익, 순위·조건검색, 시장·일정, 퇴직연금.
• 주문 — 매수·매도·정정·취소, 신용·예약·TWAP/VWAP 분할.
• 안전 코어 — 같은 주문의 중복 전송은 기본 차단되고, 타임아웃 시 재전송하지 않고 reconcile() 로 접수 여부를 직접 확인합니다. 신용거래는 기본 차단. 전송 전 리스크 한도는 KISClient(..., risk=RiskLimits(...))로 명시해 사용합니다.
• 실시간 — 시세·호가·체결통보를 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("201W09350")    # 지수옵션

4. 주문

report = kis.domestic.stock("005930").buy(quantity=10, limit_price=70000)  # 10주 매수
kis.orders.modify(report.client_order_id, limit_price=70500)   # 가격 정정
kis.orders.cancel(report.client_order_id)                      # 취소

전송 타임아웃 등으로 접수 여부가 불명일 때만 kis.orders.reconcile(report.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)로 계좌 조회·주문 미리보기와 국내 주식 주문·정정·취소 도구를 쓸 수 있습니다. 기본은 모의투자이며, 실전 주문은 이중 잠금·사람 확인·세션 서킷브레이커를 거칩니다(신규·정정은 RiskLimits 와 종목 허용목록까지; 취소는 노출을 줄이므로 제외). MCP 서버 문서를 참고하세요.

7. 문서

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

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

8. 라이선스

MIT