KIS MCP Server

[당사에서 제공하는 샘플코드에 대한 유의사항]

• 샘플 코드는 한국투자증권 Open API(KIS Developers)를 연동하는 예시입니다. 고객님의 개발 부담을 줄이고자 참고용으로 제공되고 있습니다.
• 샘플 코드는 별도의 공지 없이 지속적으로 업데이트될 수 있습니다.
• 샘플 코드를 활용하여 제작한 고객님의 프로그램으로 인한 손해에 대해서는 당사에서 책임지지 않습니다.

KIS Open API 샘플 코드 저장소 (LLM 지원)

1. 제작 의도 및 대상

🎯 제작 의도

이 저장소는 ChatGPT, Claude 등 LLM(Large Language Model) 기반 자동화 환경과 Python 개발자 모두가 한국투자증권(Korea Investment & Securities) Open API를 쉽게 이해하고 활용할 수 있도록 구성된 샘플 코드 모음입니다.

• examples_llm/: LLM이 단일 API 기능을 쉽게 탐색하고 호출할 수 있도록 구성된 기능 단위 샘플 코드
• examples_user/: 사용자가 실제 투자 및 자동매매 구현에 활용할 수 있도록 상품별로 통합된 API 호출 예제 코드
• strategy_builder/: 비주얼 UI로 매매 전략을 설계하고, 생성된 시그널 바탕으로 매수/매도 가능
• backtester/: 설계한 전략을 과거 데이터로 검증하는 백테스팅 엔진

AI와 사람이 모두 활용하기 쉬운 구조를 지향합니다.

한국투자증권 Open API 포털 바로가기

👤 대상 사용자

• 한국투자증권 Open API를 처음 사용하는 Python 개발자
• 기존 Open API 사용자 중 코드 개선 및 구조 학습이 필요한 사용자
• LLM 기반 코드 에이전트를 활용해 종목 검색, 시세 분석, 자동매매 등을 구현하고자 하는 사용자

2. 폴더 구조 및 주요 파일 설명

2.1. 폴더 구조

# 프로젝트 구조
.
├── README.md                    # 프로젝트 설명서
├── strategy_builder/            # 전략 설계 + 시그널 생성 엔진           ← New
├── backtester/                  # 백테스팅 엔진 (QuantConnect Lean)   ← New
│
├── docs/
│   └── convention.md            # 코딩 컨벤션 가이드
├── examples_llm/                  # LLM용 샘플 코드
│   ├── kis_auth.py              # 인증 공통 함수
│   ├── auth                     # 인증(토큰 발급)
│   │   ├── auth_token               # REST 접근토큰 발급
│   │   └── auth_ws_token            # 웹소켓 접속키 발급
│   ├── domestic_bond            # 국내채권
│   │   └── inquire_price        # API 단일 기능별 폴더
│   │       ├── inquire_price.py         # 한줄 호출 파일 (예: 채권 가격 조회)
│   │       └── chk_inquire_price.py     # 테스트 파일 (예: 채권 가격 조회 결과 검증)
│   ├── domestic_futureoption    # 국내선물옵션
│   ├── domestic_stock           # 국내주식
│   ├── elw                      # ELW
│   ├── etfetn                   # ETF/ETN
│   ├── overseas_futureoption    # 해외선물옵션
│   └── overseas_stock           # 해외주식
├── examples_user/                 # user용 실제 사용 예제
│   ├── kis_auth.py              # 인증 공통 함수
│   ├── auth                     # 인증(토큰 발급)
│   │   ├── auth_functions.py            # 인증 함수 모음
│   │   └── auth_examples.py             # 인증 실행 예제
│   ├── domestic_bond            # 국내채권
│   │   ├── domestic_bond_functions.py        # (REST) 통합 함수 파일 (모든 API 함수 모음)
│   │   ├── domestic_bond_examples.py         # (REST) 실행 예제 파일 (함수 사용법)
│   │   ├── domestic_bond_functions_ws.py     # (Websocket) 통합 함수 파일
│   │   └── domestic_bond_examples_ws.py      # (Websocket) 실행 예제 파일
│   ├── domestic_futureoption    # 국내선물옵션
│   ├── domestic_stock           # 국내주식
│   ├── elw                      # ELW
│   ├── etfetn                   # ETF/ETN
│   ├── overseas_futureoption    # 해외선물옵션
│   └── overseas_stock           # 해외주식
├── legacy/                      # 구 샘플코드 보관
├── stocks_info/                 # 종목정보파일 참고 데이터
├── kis_devlp.yaml               # API 설정 파일 (개인정보 입력 필요)
├── pyproject.toml               # (uv)프로젝트 의존성 관리
└── uv.lock                      # (uv)의존성 락 파일

2.2. 지원되는 주요 API 카테고리

• 아래 카테고리 및 폴더 구조는 examples_llm/, examples_user/ 폴더 모두 동일하게 적용됩니다.

2.3. 주요 파일 설명

`examples_llm/` - llm용 기능 단위 샘플 코드

API별 개별 폴더 구조: 단일 API 기능을 독립 폴더로 분리하여, LLM이 관련 코드를 쉽게 탐색할 수 있도록 구성

• 한줄 호출 파일: [함수명].py – 단일 기능을 호출하는 최소 단위 코드 (예: inquire_price.py)
• 테스트 파일: chk_[함수명].py – 호출 결과를 검증하는 테스트 실행 코드 (예: chk_inquire_price.py)

`examples_user/` - 사용자용 통합 예제 코드

카테고리별 개별 폴더 구조: 카테고리(상품)별로 모든 기능을 통합하여, 사용자가 쉽게 샘플 코드를 탐색하고 실행할 수 있도록 구성

• 통합 함수 파일: [카테고리]_functions.py - 해당 카테고리의 모든 API 기능이 통합된 함수 모음
• 실행 예제 파일: [카테고리]_examples.py - 실제 사용 예제를 기반으로 한 실행 코드
• 웹소켓 통합 함수 파일 및 실행 예제 파일: [카테고리]_functions_ws.py, [카테고리]_examples_ws.py

`kis_auth.py` - 인증 및 공통 기능

• 접근토큰 발급 및 관리
• API 호출 공통 함수
• 실전투자/모의투자 환경 전환 지원
• 웹소켓 연결 설정 기능 제공

2.4. AI 트레이딩 도구

샘플 코드 외에, Open API를 활용한 전략 설계 → 백테스팅 → 주문 실행 파이프라인을 제공합니다.

graph LR
    SB[strategy_builder] -->|".kis.yaml"| BT[backtester]
    BT -->|"검증 완료"| SB
    SB -->|"BUY/SELL/HOLD"| KIS[KIS Open API]

10개 프리셋 전략

strategy_builder와 backtester 양쪽에서 동일하게 지원합니다.