KIS Open Trading API: Python Sample Code for Korean Market Automation

Who This Repository Is For and What Problem It Solves

The KIS Open API is the official programmatic interface to Korea Investment & Securities, one of the major Korean retail brokerages. Accessing it requires a brokerage account, an approved API application, and a working understanding of the authentication flow. The repository solves the initial friction for three types of users: Python developers who are new to the API and want working examples; existing API users who want to improve their code structure; and developers building LLM-based trading agents who need single-function examples their AI tools can read and call without context-window overload.

The README states this goal directly: the repository aims to be a structure that both AI and humans can use easily. It ships a machine-readable `llms.txt` to help ChatGPT, Claude, and similar tools navigate the codebase. This is an unusual design decision for a financial API sample library and reflects the growing expectation that LLM coding agents will call brokerage APIs on behalf of users.

The repository covers eight asset categories: authentication tokens, domestic stocks, domestic bonds, domestic futures and options, overseas stocks, overseas futures and options, ELW, and ETF/ETN. Within each category, both human-friendly and LLM-friendly example styles are provided.

Dual Folder Architecture: LLM Examples and User Examples

The repository ships two parallel example folder trees for the same API surface, with different organizational philosophies.

The `examples_llm/` folder breaks each API function into its own independent folder. Each folder holds a minimal call file (for example `inquire_price.py` for a price lookup) and a test verification file (`chk_inquire_price.py`). This structure is designed so an LLM can scan a single folder and understand one API call without reading unrelated code. The README describes this as a single-function folder structure that lets an LLM easily navigate and call related code.

The `examples_user/` folder integrates all functions for a category into two files: `[category]_functions.py` (all API functions for that category combined) and `[category]_examples.py` (runnable usage examples). For websocket-based endpoints there are also `[category]_functions_ws.py` and `[category]_examples_ws.py`. This approach is better suited for a human developer who wants to see an entire asset class at once.

Both folders follow the same category structure, so finding the overseas stock price function in `examples_llm/overseas_stock/` leads to the same functionality as the equivalent function in `examples_user/overseas_stock/overseas_stock_functions.py`.

The authentication logic that both folders share lives in `kis_auth.py` at the project root. It handles access token issuance, token management, the common API call wrapper, live versus paper trading environment switching, and websocket connection setup.

Getting Started: Credentials and the First API Call

The project requires Python 3.11 or higher. The README recommends `uv` for dependency management. To install `uv` on macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the repository and install dependencies:

git clone https://github.com/koreainvestment/open-trading-api
cd open-trading-api
uv sync

Before running any sample code, you need API credentials from the Korea Investment & Securities developer portal (apiportal.koreainvestment.com). The process requires an active brokerage account, enrolling in the Open API service through the KIS website or app, and obtaining separate App Key and App Secret pairs for paper trading and live trading.

Once you have the credentials, create the configuration folder and copy the template:

mkdir -p ~/KIS/config
cp kis_devlp.yaml ~/KIS/config/

Edit `~/KIS/config/kis_devlp.yaml` to add your app keys, account numbers, and HTS ID. The live trading section of the config looks like this:

my_app: "여기에 실전투자 앱키 입력"
my_sec: "여기에 실전투자 앱시크릿 입력"
paper_app: "여기에 모의투자 앱키 입력"
paper_sec: "여기에 모의투자 앱시크릿 입력"
my_htsid: "사용자 HTS ID"
my_acct_stock: "증권계좌 8자리"

With the config in place, authenticate in Python and switch between paper and live environments:

import kis_auth as ka

# 실전투자 인증
ka.auth(svr="prod", product="01") # 모의투자: svr="vps"

Passing `svr="vps"` directs the API calls to the paper trading environment, which uses separate credentials from the `paper_app` and `paper_sec` fields. All sample code in `examples_user/` is gated behind this authentication call.

Strategy Builder and the .kis.yaml Pipeline

Beyond sample code, the repository includes a full algorithmic trading pipeline with three components: `strategy_builder/`, `backtester/`, and `MCP/`.

The `strategy_builder/` component provides a visual UI for designing trading strategies. It ships 80 technical indicators and 10 preset strategies covering a range of approaches. The preset list includes a Golden Cross (short moving average crossing above the long), Momentum (buying recent top performers), 52-week high breakout, consecutive up/down day detection, disparity index (identifying overbought or oversold conditions), failed breakout stop-loss, strong-close momentum, volatility expansion, mean reversion, and a trend filter. Each preset can be customized in the UI.

When a strategy is ready, the builder exports it as a `.kis.yaml` file. This format acts as a shared contract between the builder and the backtester: importing a `.kis.yaml` into `backtester/` replays the strategy against historical data without reconfiguring it by hand.

The `backtester/` component runs QuantConnect Lean in Docker. It produces HTML reports after running a backtest, and it supports parameter optimization. Docker Desktop is required for this component; it will not run on the Python dependencies alone.

The `MCP/` directory provides an AI tool connection layer called KIS Code Assistant and Trading MCP, intended for integrating the KIS API with AI coding environments.

These three components add significant setup overhead compared to the sample code folders. The README notes that Node.js 18 or higher is required for the strategy_builder and backtester frontends, in addition to Docker Desktop.

Limitations: KIS Accounts Only and No License on Record

The most important constraint is that none of the sample code works without a Korea Investment & Securities brokerage account and an approved API application. There is no demo mode, no mock API, and no public sandbox. A developer outside Korea, or one without an existing KIS account, cannot run a single function from this repository.

The repository's license field is blank. The README does not specify a license, and the `pyproject.toml` omits the license key. This means the default copyright rules apply: the code is the intellectual property of Korea Investment & Securities, and copying, modifying, or redistributing it for commercial use is not permitted without explicit consent. The README's disclaimer also states that the company takes no responsibility for losses arising from use of the sample code.

The backtester depends on QuantConnect Lean, which is a separate project with its own license and its own prerequisites. Running Lean on the sample historical data the backtester expects requires additional setup not documented in this repository's README.

Finally, the scope is limited to KIS. There is no support for other Korean brokerages, foreign markets directly through KIS beyond what the API supports, or crypto exchanges. Developers building multi-broker systems will need separate integrations.

Comparison with Foreign Brokerage API Libraries

The closest analogy in a different market is the Alpaca trading API Python client, which serves US equity markets. Alpaca provides a first-party Python SDK with a paper trading sandbox, commission-free trading, and open-source client libraries. It does not require a traditional brokerage account setup and offers fractional shares.

By contrast, koreainvestment/open-trading-api is a sample code collection rather than a packaged SDK. There is no installable Python package from PyPI; you clone the repository and import files directly. The authentication model requires a full brokerage account, and there is no equivalent to Alpaca's sandbox that works without real credentials.

For Korean domestic market access, this repository is the official path from Korea Investment & Securities. It covers more asset classes than most third-party alternatives, including domestic bonds and futures, and has the advantage of being maintained by the brokerage itself. The trade-off is the higher setup barrier and the absence of a proper SDK interface.

Maintenance and Usage Terms

The repository is not archived. The last push was on 2026-08-26, which is recent. The README states explicitly that sample code may be updated continuously without separate notice, which is useful to know: a `git pull` at any time could change example behavior.

There are no GitHub releases. The project version in `pyproject.toml` is `1.0.0`, which suggests the maintainers consider the core sample structure stable, even without a formal release process.

The README includes a section on coding conventions at `docs/convention.md`, which indicates that contributions are at least informally structured. There is no CHANGELOG or migration document.

The dependency set is modest for the sample code itself: `pandas`, `pycryptodome`, `pyqt6`, `pyside6`, `pyyaml`, `requests`, and `websockets`. The pyqt6 and pyside6 dependencies are for the strategy_builder GUI; developers using only the sample code folders do not need them but they are installed as part of `uv sync`.

Editorial conclusion

This repository is the right starting point for a Python developer with an active Korea Investment & Securities account who wants to automate domestic or overseas trading via the KIS Open API. It is not a standalone trading system; you must apply for API access through the KIS developer portal before any sample code will execute. Developers planning to use the strategy_builder or backtester components should confirm that their environment meets the Node.js 18 and Docker Desktop requirements, since those components will not run on Python dependencies alone. The license field in the repository is undocumented, so any commercial or redistributed use requires direct clarification from Korea Investment & Securities.

Frequently asked questions

Official sources

1. Issues
2. koreainvestment/open-trading-api on GitHub
3. Project website
4. README