{"id":35094337,"url":"https://github.com/koreainvestment/open-trading-api","last_synced_at":"2026-04-22T10:00:44.976Z","repository":{"id":37478928,"uuid":"479235940","full_name":"koreainvestment/open-trading-api","owner":"koreainvestment","description":"Korea Investment \u0026 Securities Open API Github","archived":false,"fork":false,"pushed_at":"2026-03-16T23:20:34.000Z","size":33196,"stargazers_count":1115,"open_issues_count":26,"forks_count":604,"subscribers_count":36,"default_branch":"main","last_synced_at":"2026-03-17T09:51:37.611Z","etag":null,"topics":["ai-trading","api-samples","autotrade","chatgpt","claude","finance","investment","koreainvestment","llm","mcp","open-trading-api","openapi","python","realtime","rest-api","stock-trading","stocks","trading","trading-api","websocket"],"latest_commit_sha":null,"homepage":"https://apiportal.koreainvestment.com","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koreainvestment.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-08T03:51:49.000Z","updated_at":"2026-03-17T05:09:38.000Z","dependencies_parsed_at":"2026-02-20T10:16:06.100Z","dependency_job_id":null,"html_url":"https://github.com/koreainvestment/open-trading-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/koreainvestment/open-trading-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koreainvestment%2Fopen-trading-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koreainvestment%2Fopen-trading-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koreainvestment%2Fopen-trading-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koreainvestment%2Fopen-trading-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koreainvestment","download_url":"https://codeload.github.com/koreainvestment/open-trading-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koreainvestment%2Fopen-trading-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32130776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T08:34:57.708Z","status":"ssl_error","status_checked_at":"2026-04-22T08:34:55.583Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-trading","api-samples","autotrade","chatgpt","claude","finance","investment","koreainvestment","llm","mcp","open-trading-api","openapi","python","realtime","rest-api","stock-trading","stocks","trading","trading-api","websocket"],"created_at":"2025-12-27T15:04:24.315Z","updated_at":"2026-04-22T10:00:44.963Z","avatar_url":"https://github.com/koreainvestment.png","language":"Python","readme":"**[당사에서 제공하는 샘플코드에 대한 유의사항]**\n\n- 샘플 코드는 한국투자증권 Open API(KIS Developers)를 연동하는 예시입니다. 고객님의 개발 부담을 줄이고자 참고용으로 제공되고 있습니다.\n- 샘플 코드는 별도의 공지 없이 지속적으로 업데이트될 수 있습니다.\n- 샘플 코드를 활용하여 제작한 고객님의 프로그램으로 인한 손해에 대해서는 당사에서 책임지지 않습니다.\n\n# KIS Open API 샘플 코드 저장소 (LLM 지원)\n\n## 1. 제작 의도 및 대상\n\n### 🎯 제작 의도\n\n이 저장소는 **ChatGPT, Claude 등 LLM(Large Language Model)** 기반 자동화 환경과 Python 개발자 모두가\n**한국투자증권(Korea Investment \u0026 Securities) Open API를 쉽게 이해하고 활용**할 수 있도록 구성된 샘플 코드 모음입니다.\n\n- `examples_llm/`: LLM이 단일 API 기능을 쉽게 탐색하고 호출할 수 있도록 구성된 기능 단위 샘플 코드\n- `examples_user/`: 사용자가 실제 투자 및 자동매매 구현에 활용할 수 있도록 상품별로 통합된 API 호출 예제 코드\n- `strategy_builder/`: 비주얼 UI로 매매 전략을 설계하고, 생성된 시그널 바탕으로 매수/매도 가능\n- `backtester/`: 설계한 전략을 과거 데이터로 검증하는 백테스팅 엔진\n\n\u003e AI와 사람이 모두 활용하기 쉬운 구조를 지향합니다.\n\n[한국투자증권 Open API 포털 바로가기](https://apiportal.koreainvestment.com/)\n\n### 👤 대상 사용자\n\n- 한국투자증권 Open API를 처음 사용하는 Python 개발자\n- 기존 Open API 사용자 중 코드 개선 및 구조 학습이 필요한 사용자\n- LLM 기반 코드 에이전트를 활용해 종목 검색, 시세 분석, 자동매매 등을 구현하고자 하는 사용자\n\n## 2. 폴더 구조 및 주요 파일 설명\n\n### 2.1. 폴더 구조\n\n```\n# 프로젝트 구조\n.\n├── README.md                    # 프로젝트 설명서\n├── strategy_builder/            # 전략 설계 + 시그널 생성 엔진           ← New\n├── backtester/                  # 백테스팅 엔진 (QuantConnect Lean)   ← New\n│\n├── docs/\n│   └── convention.md            # 코딩 컨벤션 가이드\n├── examples_llm/                  # LLM용 샘플 코드\n│   ├── kis_auth.py              # 인증 공통 함수\n│   ├── auth                     # 인증(토큰 발급)\n│   │   ├── auth_token               # REST 접근토큰 발급\n│   │   └── auth_ws_token            # 웹소켓 접속키 발급\n│   ├── domestic_bond            # 국내채권\n│   │   └── inquire_price        # API 단일 기능별 폴더\n│   │       ├── inquire_price.py         # 한줄 호출 파일 (예: 채권 가격 조회)\n│   │       └── chk_inquire_price.py     # 테스트 파일 (예: 채권 가격 조회 결과 검증)\n│   ├── domestic_futureoption    # 국내선물옵션\n│   ├── domestic_stock           # 국내주식\n│   ├── elw                      # ELW\n│   ├── etfetn                   # ETF/ETN\n│   ├── overseas_futureoption    # 해외선물옵션\n│   └── overseas_stock           # 해외주식\n├── examples_user/                 # user용 실제 사용 예제\n│   ├── kis_auth.py              # 인증 공통 함수\n│   ├── auth                     # 인증(토큰 발급)\n│   │   ├── auth_functions.py            # 인증 함수 모음\n│   │   └── auth_examples.py             # 인증 실행 예제\n│   ├── domestic_bond            # 국내채권\n│   │   ├── domestic_bond_functions.py        # (REST) 통합 함수 파일 (모든 API 함수 모음)\n│   │   ├── domestic_bond_examples.py         # (REST) 실행 예제 파일 (함수 사용법)\n│   │   ├── domestic_bond_functions_ws.py     # (Websocket) 통합 함수 파일\n│   │   └── domestic_bond_examples_ws.py      # (Websocket) 실행 예제 파일\n│   ├── domestic_futureoption    # 국내선물옵션\n│   ├── domestic_stock           # 국내주식\n│   ├── elw                      # ELW\n│   ├── etfetn                   # ETF/ETN\n│   ├── overseas_futureoption    # 해외선물옵션\n│   └── overseas_stock           # 해외주식\n├── legacy/                      # 구 샘플코드 보관\n├── stocks_info/                 # 종목정보파일 참고 데이터\n├── kis_devlp.yaml               # API 설정 파일 (개인정보 입력 필요)\n├── pyproject.toml               # (uv)프로젝트 의존성 관리\n└── uv.lock                      # (uv)의존성 락 파일\n```\n\n### 2.2. 지원되는 주요 API 카테고리\n\n- 아래 카테고리 및 폴더 구조는 examples_llm/, examples_user/ 폴더 모두 동일하게 적용됩니다.\n\n| 카테고리 | 설명 | 폴더명 |\n| --- | --- | --- |\n| 인증 | 접근토큰 발급, 웹소켓 접속키 발급 | `auth` |\n| 국내주식 | 국내 주식 시세, 주문, 잔고 등 | `domestic_stock` |\n| 국내채권 | 국내 채권 시세, 주문 등 | `domestic_bond` |\n| 국내선물옵션 | 국내 파생상품 관련 | `domestic_futureoption` |\n| 해외주식 | 해외 주식 시세, 주문 등 | `overseas_stock` |\n| 해외선물옵션 | 해외 파생상품 관련 | `overseas_futureoption` |\n| ELW | ELW 시세 API | `elw` |\n| ETF/ETN | ETF, ETN 시세 API | `etfetn` |\n\n### 2.3. 주요 파일 설명\n\n### `examples_llm/` - llm용 기능 단위 샘플 코드\n\n**API별 개별 폴더 구조**: 단일 API 기능을 독립 폴더로 분리하여, LLM이 관련 코드를 쉽게 탐색할 수 있도록 구성\n- **한줄 호출 파일**: `[함수명].py` – 단일 기능을 호출하는 최소 단위 코드 (예: `inquire_price.py`)\n- **테스트 파일**: `chk_[함수명].py` – 호출 결과를 검증하는 테스트 실행 코드 (예: `chk_inquire_price.py`)\n\n### `examples_user/` - 사용자용 통합 예제 코드\n\n**카테고리별 개별 폴더 구조**: 카테고리(상품)별로 모든 기능을 통합하여, 사용자가 쉽게 샘플 코드를 탐색하고 실행할 수 있도록 구성\n- **통합 함수 파일**: `[카테고리]_functions.py` - 해당 카테고리의 모든 API 기능이 통합된 함수 모음\n- **실행 예제 파일**: `[카테고리]_examples.py` - 실제 사용 예제를 기반으로 한 실행 코드\n- **웹소켓 통합 함수 파일 및 실행 예제 파일**: `[카테고리]_functions_ws.py`, `[카테고리]_examples_ws.py`\n\n### `kis_auth.py` - 인증 및 공통 기능\n\n- 접근토큰 발급 및 관리\n- API 호출 공통 함수\n- 실전투자/모의투자 환경 전환 지원\n- 웹소켓 연결 설정 기능 제공\n\n### 2.4. AI 트레이딩 도구\n\n샘플 코드 외에, Open API를 활용한 **전략 설계 → 백테스팅 → 주문 실행** 파이프라인을 제공합니다.\n\n```mermaid\ngraph LR\n    SB[strategy_builder] --\u003e|\".kis.yaml\"| BT[backtester]\n    BT --\u003e|\"검증 완료\"| SB\n    SB --\u003e|\"BUY/SELL/HOLD\"| KIS[KIS Open API]\n```\n\n| 디렉토리 | 역할 | 상세 |\n|----------|------|------|\n| `strategy_builder/` | 전략 설계 + 시그널 생성 | 80개 기술지표, 10개 프리셋 전략, BUY/SELL/HOLD 신호 ([README](strategy_builder/README.md)) |\n| `backtester/` | 과거 검증 + 파라미터 최적화 | Docker 기반 QuantConnect Lean, HTML 리포트 ([README](backtester/README.md)) |\n| `MCP/` | AI 도구 연결 | KIS Code Assistant + Trading MCP ([README](MCP/README.MD)) |\n\n#### 10개 프리셋 전략\n\n`strategy_builder`와 `backtester` 양쪽에서 동일하게 지원합니다.\n\n| # | 전략명 | 유형 | 한줄 설명 |\n|---|--------|------|-----------|\n| 01 | 골든크로스 | 추세추종 | 단기 이동평균이 장기 이동평균을 상향 돌파하면 매수 |\n| 02 | 모멘텀 | 추세추종 | 최근 N일 수익률이 높은 종목을 매수 |\n| 03 | 52주 신고가 | 돌파매매 | 종가가 52주 최고가를 갱신하면 매수 |\n| 04 | 연속 상승/하락 | 추세추종 | N일 연속 종가 상승 시 매수, N일 연속 하락 시 매도 |\n| 05 | 이격도 | 역추세 | 종가/이동평균 비율로 과열(매도)·침체(매수) 판단 |\n| 06 | 돌파 실패 | 손절 | 전고점 돌파 후 다시 아래로 빠지면 손절 |\n| 07 | 강한 종가 | 모멘텀 | 종가가 당일 고가 근처에서 마감하면 매수 |\n| 08 | 변동성 확장 | 돌파매매 | 변동성이 줄어든 뒤 급등하면 매수 |\n| 09 | 평균회귀 | 역추세 | 가격이 평균에서 크게 벗어나면 반대 방향으로 매매 |\n| 10 | 추세 필터 | 추세추종 | 장기 이동평균 위에서 상승 중이면 매수 |\n\n#### .kis.yaml — 공유 전략 포맷\n\n`strategy_builder`에서 설계한 전략을 `.kis.yaml`로 내보내면, `backtester`에서 그대로 Import하여 백테스트를 수행할 수 있습니다.\n포맷 상세는 [strategy_builder/README.md](strategy_builder/README.md#kisyaml-포맷) 또는 [backtester/README.md](backtester/README.md#kisyaml-포맷)를 참고하세요.\n\n## 3. 사전 환경설정 안내\n\n### 3.1. Python 환경 요구사항\n\n- **Python 3.11 이상** 필요\n- **uv** **패키지 매니저 사용** 권장 (빠르고 간편한 의존성 관리)\n\n### 3.2. uv 설치 방법\n\n- 간편 설정을 위해 uv를 권장합니다\n\n```bash\n# Windows (PowerShell)\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 설치 확인\nuv --version\n# uv 0.x.x ... -\u003e 설치 완료\n```\n\n### 3.3. 프로젝트 클론 및 환경 설정\n\n```bash\n# 저장소 클론\ngit clone https://github.com/koreainvestment/open-trading-api\ncd open-trading-api\n\n# uv를 사용한 의존성 설치 - 한줄로 끝\nuv sync\n```\n\n### 3.4. KIS Open API 신청 및 설정\n\n🍀 [서비스 신청 안내 바로가기](https://apiportal.koreainvestment.com/about-howto)\n1. 한국투자증권 **계좌 개설 및 ID 연결**\n2. 한국투자증권 홈페이지 or 앱에서 **Open API 서비스 신청**\n3. **앱키(App Key)**, **앱시크릿(App Secret)** 발급\n4. **모의투자** 및 **실전투자** 앱키 각각 준비\n\n### 3.5. kis_devlp.yaml 설정\n\n- 본인의 계정 설정을 위해 `kis_devlp.yaml` 파일을 수정합니다.\n- 기본 경로는 `~/KIS/config/kis_devlp.yaml`입니다. 폴더가 없으면 생성해 주세요.\n- 프로젝트 루트의 `kis_devlp.yaml`을 `~/KIS/config/`로 복사한 뒤 수정하는 것을 권장합니다.\n- 경로를 변경하고 싶다면 `kis_auth.py`의 `config_root` 값을 수정하면 됩니다.\n\n```bash\n# 설정 폴더 생성 및 파일 복사\nmkdir -p ~/KIS/config\ncp kis_devlp.yaml ~/KIS/config/\n```\n\n1. `~/KIS/config/kis_devlp.yaml` 파일 열기\n2. **앱키와 앱시크릿** 정보 입력\n3. **HTS ID** 정보 입력\n4. **계좌번호** 정보 입력 (앞 8자리와 뒤 2자리 구분)\n5. **저장** 후 닫기\n\n```yaml\n# 실전투자\nmy_app: \"여기에 실전투자 앱키 입력\"\nmy_sec: \"여기에 실전투자 앱시크릿 입력\"\n\n# 모의투자\npaper_app: \"여기에 모의투자 앱키 입력\"\npaper_sec: \"여기에 모의투자 앱시크릿 입력\"\n\n# HTS ID(KIS Developers 고객 ID) - 체결통보, 나의 조건 목록 확인 등에 사용됩니다.\nmy_htsid: \"사용자 HTS ID\"\n\n# 계좌번호 앞 8자리\nmy_acct_stock: \"증권계좌 8자리\"\nmy_acct_future: \"선물옵션계좌 8자리\"\nmy_paper_stock: \"모의투자 증권계좌 8자리\"\nmy_paper_future: \"모의투자 선물옵션계좌 8자리\"\n\n# 계좌번호 뒤 2자리\nmy_prod: \"01\" # 종합계좌\n# my_prod: \"03\" # 국내선물옵션 계좌\n# my_prod: \"08\" # 해외선물옵션 계좌\n# my_prod: \"22\" # 개인연금 계좌\n# my_prod: \"29\" # 퇴직연금 계좌\n\n# User-Agent(기본값 사용 권장, 변경 불필요)\nmy_agent: \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36\"\n```\n\n### 3.6. 실행파일 내 인증 설정 검토\n\n- 실행하려는 파일에서 인증 관련 설정을 검토 혹은 변경해줍니다. 국내주식 기능 전체를 이용하시려면, `domestic_stock/domestic_stock_examples.py` 파일을 확인해주세요. \nka.auth() 함수의 svr, product 매개변수를 아래와 같이 수정하면 실전환경(prod)에서 위탁계좌(-01)로 매매 테스트가 가능합니다.\n\n```python\nimport kis_auth as ka\n\n# 실전투자 인증\nka.auth(svr=\"prod\", product=\"01\") # 모의투자: svr=\"vps\"\n```\n\n### 3.7. 전략 빌더 / 백테스터 환경 설정 (선택)\n\n전략 설계 및 백테스팅 기능을 사용하려면 추가 설정이 필요합니다.\n\n| 항목 | 설치 | 용도 |\n|------|------|------|\n| Node.js 18+ | [nodejs.org](https://nodejs.org/) | strategy_builder, backtester 프론트엔드 |\n| Docker Desktop | [docker.com](https://www.docker.com/products/docker-desktop) | backtester (Lean 엔진) |\n\n## 4. 샘플 코드 실행\n\n### 4.1. 샘플 코드 실행\n\n- **examples_user 기준**\n\n```bash\n# 국내주식 샘플 코드 실행 (examples_user/domestic_stock/)\nuv run python domestic_stock_examples.py # REST 방식\nuv run python domestic_stock_examples_ws.py  # Websocket 방식 \n```\n\ndomestic_stock_examples.py에는 여러 함수가 포함되어 있으므로, 사용하려는 함수만 남기고 나머지는 주석 처리한 후, 입력값을 수정하여 호출해 주세요.\n\n- **examples_llm 기준**\n\n```bash\n# 국내주식 \u003e 주식현재가 시세 샘플 코드 실행 (examples_llm/domestic_stock/inquire_price/)\nuv run python chk_inquire_price.py\n```\n\nexamples_llm 은 각 기능별로 개별 실행 파일(chk_*.py)이 분리되어 있어, 특정 기능만 테스트하고자 할 때 유용합니다.\n\n### 4.2. 예제 코드 샘플 (examples_user)\n\n```python\n# REST API 호출 예제 - domestic_stock_examples.py\nimport sys\nimport logging\nimport pandas as pd\nsys.path.extend(['..', '.'])\n\nimport kis_auth as ka\nfrom domestic_stock_functions import *\n\n# 로깅 설정\nlogging.basicConfig(level=logging.INFO, format='%(levelname)s - %(message)s')\nlogger = logging.getLogger(__name__)\n\n# 인증\nka.auth()\ntrenv = ka.getTREnv()\n\n# 삼성전자 현재가 시세 조회\nresult = inquire_price(env_dv=\"real\", fid_cond_mrkt_div_code=\"J\", fid_input_iscd=\"005930\")\nprint(result)\n```\n\n```python\n# 웹소켓 호출 예제 - domestic_stock_examples_ws.py\nimport sys\nimport logging\nimport pandas as pd\nsys.path.extend(['..', '.'])\n\nimport kis_auth as ka\nfrom domestic_stock_functions_ws import *\n\n# 로깅 설정\nlogging.basicConfig(level=logging.INFO, format='%(levelname)s - %(message)s')\nlogger = logging.getLogger(__name__)\n\n# 인증\nka.auth()\nka.auth_ws()\ntrenv = ka.getTREnv()\n\n# 웹소켓 선언\nkws = ka.KISWebSocket(api_url=\"/tryitout\")\n\n# 삼성전자, sk하이닉스 실시간 호가 구독\nkws.subscribe(request=asking_price_krx, data=[\"005930\", \"000660\"])\n```\n\n### 4.3. 전략 빌더 / 백테스터 실행\n\n```bash\n# Strategy Builder (전략 설계 + 시그널)\ncd strategy_builder\n./start.sh\n\n# Backtester (백테스팅)\ncd backtester\n./start.sh\n```\n\n상세 실행 방법은 각 디렉토리의 README를 참고하세요:\n- [strategy_builder/README.md](strategy_builder/README.md)\n- [backtester/README.md](backtester/README.md)\n\n## 5. 문제 해결 가이드\n\n### 토큰 오류 시\n\n```python\nimport kis_auth as ka\n\n# 토큰 재발급 - 1분당 1회 발급됩니다.\nka.auth(svr=\"prod\")  # 또는 \"vps\"\n```\n\n### 설정 파일 오류 시\n\n- `kis_devlp.yaml` 파일의 앱키, 앱시크릿이 올바른지 확인\n- 계좌번호 형식이 맞는지 확인 (앞 8자리 + 뒤 2자리)\n- 실시간 시세(WebSocket) 이용 중 ‘No close frame received’ 오류가 발생하는 경우, `kis_devlp.yaml`에 입력하신 HTS ID가 정확한지 확인\n\n### 의존성 오류 시\n\n```bash\n# 의존성 재설치\nuv sync --reinstall\n```\n\n### Docker 오류 (backtester)\n\n```bash\ndocker info              # Docker Desktop 실행 상태 확인\ndocker images | grep lean # Lean 이미지 확인 (첫 실행 시 자동 다운로드)\n```\n\n### 초당 거래건수 초과 (`EGW00201`)\n\n모의투자 계좌는 REST API 호출 제한이 낮습니다.\n단일 조회에는 문제없으나, 파라미터 최적화처럼 연속 호출이 많으면 실전투자 계좌를 권장합니다.\n\n---\n\n# 📧 문의사항\n\n- [💬 한국투자증권 Open API 챗봇](https://chatgpt.com/g/g-68b920ee7afc8191858d3dc05d429571-hangugtujajeunggweon-open-api-seobiseu-gpts)에 언제든 궁금한 점을 물어보세요.\n","funding_links":[],"categories":["📚 Projects (1974 total)","Code \u0026 Developer Tools"],"sub_categories":["Tools \u0026 Libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoreainvestment%2Fopen-trading-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoreainvestment%2Fopen-trading-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoreainvestment%2Fopen-trading-api/lists"}