Skip to content

kiwoom-client

kiwoom-client kiwoom-client

The Kiwoom REST API, from Python and AI agents.

An unofficial open-source Python client for the Kiwoom Securities REST API: 182 endpoints, condition search and real-time WebSocket. MCP server built in.

Quick start GitHub PyPI

  • Easy


    pip install, add your app key and secret, done. Token issue, refresh before expiry, 401 reissue, per-TR rate limiting and pagination are handled for you. No COM/OCX, so it runs on Windows, macOS and Linux.

  • AI-native


    One command, kiwoom-client-mcp, gives Claude Code and Cursor all 182 REST endpoints and the 4 condition-search calls as MCP tools. to_dataframe() turns responses into numbers you can compute with.

  • Live orders need your say-so


    Against a live (실전투자) account the 12 order tools are not even registered until you set KIWOOM_MCP_ALLOW_LIVE_ORDERS=true. The agent never learns they exist.

Quick start

pip install kiwoom-client
from kiwoom_client import KiwoomAPI

api = KiwoomAPI(app_key="YOUR_APP_KEY", app_secret="YOUR_APP_SECRET", is_mock=True)  # True = mock trading

info = api.stock_info.basic_stock_info(stk_cd="005930")                   # Samsung Electronics
chart = api.chart.stock_daily_chart(stk_cd="005930", base_dt="20260326", upd_stkpc_tp="1")  # daily chart
print(info["stk_nm"])

Get an app key and secret at the Kiwoom REST API portal and start on the mock server (is_mock=True).

The default is the live server

KiwoomAPI(...) defaults to is_mock=False (live). With live keys, api.order.* and api.credit_order.* place real orders. The MCP live-order guard covers the MCP server only, not direct Python calls.

Where to next

I want to Go to
Read the full usage guide (sync/async, WebSocket, errors) README
Install and make a first call on macOS, Linux or a server macOS and Linux
Look up an api_id or TR name among the 182 methods Endpoint reference
Connect it to Claude Code or Cursor MCP server
Port OpenAPI+ / pykiwoom code to REST Migration table
Compare with OpenAPI+, pykiwoom and other REST wrappers Why kiwoom-client
Public projects built on it Showcase
Kiwoom portal, MCP and public-data links Resources
Report a bug or ask for a feature GitHub Issues

kiwoom-client is an unofficial open-source project, not affiliated with or endorsed by Kiwoom Securities. "Kiwoom" is a trademark of Kiwoom Securities Co., Ltd.; this project is only a client for its public REST API.