koreainvestment/open-trading-api: KIS sample code, an LLM-oriented layout, and a bundled strategy pipeline

The gap this fills: an API portal with no runnable Python

Korea Investment & Securities publishes its Open API through a separate portal, apiportal.koreainvestment.com. What the portal does not give you, based on this repository's framing, is runnable Python. The README describes the project as a collection of sample code whose purpose is to reduce the development burden of integrating the KIS Developers Open API, and it states plainly that the company accepts no liability for losses caused by programs built from it. That sentence sets the contract: you get examples, you own the result. The intended audience is narrow and explicit. Python developers using the KIS Open API for the first time, existing API users who want to study a cleaner structure, and people driving code agents such as ChatGPT or Claude to implement symbol search, quote analysis or automated trading. If you are not integrating this specific broker's API, nothing here transfers. The endpoints, the token flow and the account model are all KIS-specific.

Two parallel trees: examples_llm for agents, examples_user for humans

The organizing decision in this repository is that the same API surface is presented twice, with different granularity. examples_llm breaks each single API function into its own folder. Inside a folder such as domestic_bond/inquire_price you get inquire_price.py, described as a one-line call file, and chk_inquire_price.py, a test file that verifies the result of that call. The stated reason is retrieval: an LLM looking for bond price inquiry can find one small file rather than a thousand-line module. examples_user inverts the layout. Each product category gets a consolidated functions file holding every API function for that category, a matching examples file showing how to call them, and websocket counterparts suffixed _ws. So domestic_bond contains domestic_bond_functions.py, domestic_bond_examples.py, domestic_bond_functions_ws.py and domestic_bond_examples_ws.py. Both trees cover the same eight categories: auth, domestic_stock, domestic_bond, domestic_futureoption, overseas_stock, overseas_futureoption, elw and etfetn. The duplication is deliberate and it is also the repository's main maintenance risk. Two trees covering the same endpoints means two places to update when an endpoint changes, and the README notes the samples may be updated continuously without separate notice.

What kis_auth.py actually centralizes

Authentication is the one piece both trees share, and the README lists four responsibilities for kis_auth.py: issuing and managing the access token, providing a common API call function, switching between live and paper trading environments, and configuring websocket connections. The token endpoints themselves live under the auth category, split into auth_token for the REST access token and auth_ws_token for the websocket connection key. In examples_user the auth folder holds auth_functions.py and auth_examples.py instead of the per-endpoint folders used in examples_llm. The practical consequence is that a token is issued once and reused, and the live versus paper switch is a configuration concern rather than something you thread through every call site. The README does not document token expiry handling, refresh timing or rate limits in the material available here, so treat that as something to confirm against the portal before you build retry logic around it.

Getting it running: uv, a cloned config, and two keys per environment

The README requires Python 3.11 or later and recommends uv for dependency management, offering install commands for Windows PowerShell and for macOS or Linux, then uv --version to confirm. The project itself is cloned and synced in two steps: git clone https://github.com/koreainvestment/open-trading-api followed by cd open-trading-api and uv sync. Dependencies are declared in pyproject.toml with uv.lock as the lock file, so uv sync is the whole install. Configuration is the part people get wrong. You need an App Key and App Secret from the KIS portal, and the README instructs you to prepare separate keys for paper trading and for live trading. Those values go into kis_devlp.yaml. The default path the code reads is ~/KIS/config/kis_devlp.yaml, and the README recommends copying the repository-root kis_devlp.yaml there before editing it, with mkdir -p ~/KIS/config and cp kis_devlp.yaml ~/KIS/config/. If you want the file somewhere else, the config_root value in kis_auth.py is what you change. Note the asymmetry: the repository ships a template, but the code reads from your home directory, so editing the file in the clone alone will not take effect.

strategy_builder, the .kis.yaml handoff, and a Lean backtester in Docker

Beyond samples, the repository ships a pipeline. strategy_builder is described as a visual UI for designing trading strategies and generating buy and sell signals, with 80 technical indicators and 10 preset strategies. backtester is a separate engine built on QuantConnect Lean, run through Docker, that validates a strategy against historical data and produces an HTML report. The coupling between them is a file format: strategy_builder exports a .kis.yaml document, backtester imports it, and the README's diagram shows the validation result flowing back to strategy_builder before BUY, SELL or HOLD signals reach the KIS Open API. The 10 presets are named and described one line each, including golden cross, momentum, 52-week high breakout, consecutive up or down days, displacement ratio, failed breakout, strong close, volatility expansion, mean reversion and a trend filter. There is also an MCP directory containing a KIS Code Assistant and a Trading MCP server. Two caveats belong here rather than in a footnote. First, the backtester depends on Docker and on Lean, which is a substantial external toolchain compared with the rest of the repository. Second, the README gives no accuracy, slippage or fill-model details for the backtester in the material available, so an HTML report should be read as a relative comparison between parameter sets, not as an expected return.

Where this repository is the wrong tool

The README's own disclaimer is the first limitation: the code is provided for reference, may be updated without notice, and the company disclaims liability for losses from programs built with it. That is not boilerplate to skim past. It means there is no versioned API contract here, no support channel described in the material, and no release history retrieved for this repository, so you cannot pin a sample to a compatibility guarantee. The second limitation is structural. Sample code that issues real orders is dangerous by default, because the shortest path to running an example is often the live environment. The live-versus-paper switch in kis_auth.py exists, but nothing in the README forces a dry run before an order call. Third, the two-tree layout means an endpoint fix may land in examples_llm and not yet in examples_user, or the reverse. If you copy from one tree and debug against the other, you can spend time on a discrepancy that is just staleness. Finally, if your requirement is a supported client library with semantic versioning, deprecation policy and a changelog, this is not that, and no amount of reading the folder structure will make it that.

Alternatives: a maintained client library versus copy-and-adapt samples

The realistic alternative is not another broker's samples, it is a community-maintained Python client for the same KIS Open API, distributed as an installable package. The difference in approach is ownership of the update problem. With this repository you copy a function into your project and you own it from that moment; when KIS changes a field or a path, you diff your copy against the repository and reconcile by hand, across whichever of the two trees you borrowed from. With a published client you declare a version in pyproject.toml, and the maintainer absorbs endpoint changes into a new release. You trade control for maintenance. The counter-argument for the official samples is that they come from the broker, they cover the full category list including ELW and ETF/ETN, and they include the websocket variants that a community client may or may not implement. If you want the strategy_builder and backtester pipeline, no external client replaces that, because the pipeline is not a client at all. Pick based on whether your bottleneck is writing the first correct call or keeping a hundred calls correct over a year.

Licence, maintenance and what to check before you commit

The licence is not identified in the repository metadata available here, and no releases were retrieved. Both facts matter for adoption. Without a stated licence you do not have a documented grant to redistribute the code, so copying samples into a commercial product is a question for your own legal review rather than something this article can settle. Without releases there is no version to pin and no changelog to read, which is consistent with the README's statement that samples may be updated without notice. Practically, that pushes you toward vendoring specific files and recording where each came from, rather than depending on the repository as a package. The maintenance cost is therefore front-loaded: reading the convention guide in docs/convention.md, understanding the shared kis_auth.py, and deciding which tree you will track. The upgrade cost is the diff you run when an endpoint starts returning errors. Before any of that, confirm Python 3.11 or later is available, that uv sync completes, and that ~/KIS/config/kis_devlp.yaml holds paper-trading credentials rather than live ones for your first end-to-end run.

Editorial conclusion

Adopt this repository if you are writing Python against the Korea Investment & Securities Open API and want a working starting point for token issuance, quotes, orders and websocket subscriptions across domestic stock, bond, futures and options, overseas stock, ELW and ETF/ETN. Do not adopt it as a production dependency, and do not treat the strategy_builder or backtester as validated trading systems. Before writing any order code, verify three things: that your own App Key and App Secret are issued for the environment you intend to trade, that ~/KIS/config/kis_devlp.yaml exists and points at the right account, and that the specific endpoint folder you plan to copy still matches the current API portal documentation, because the README states the samples can be updated without notice.

Official sources

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