Skip to content

Why kiwoom-client

There are two ways to automate Kiwoom Securities from Python: libraries around the older OpenAPI+ (OCX/COM), and libraries around the newer Kiwoom REST API. This page compares the two, and the REST alternatives, on facts. The right pick depends on what you are building, so read "When to pick something else" too.

OpenAPI+ (OCX) vs. the REST API

OpenAPI+ (OCX/COM) Kiwoom REST API
Interface Windows COM control + event callbacks HTTPS (JSON) + WebSocket
OS Windows only Windows, macOS, Linux
Python 32-bit only for a long time, tied to a Qt event loop 64-bit, plain asyncio or threads
Servers, Docker, cloud Hard: needs a GUI session Headless
Login OpenAPI login window (manual, or auto-login setting) Token from app key + secret

Moving to REST lets you run on a Linux server or a Mac without anyone clicking a login window. Some OpenAPI+ features may not exist in REST yet, so look up the TRs you rely on in the Kiwoom REST API guide first. What kiwoom-client wraps is listed in the endpoint reference; the OpenAPI+ TR and function mapping is in Moving from OpenAPI+ (OCX) and pykiwoom.

Python libraries at a glance

As of 2026-11-21, from PyPI metadata and each project's README. Versions and features change; check each project before you choose.

Official, from Kiwoom Securities

Repository / package Latest (uploaded) Python License Stated in its README
Kiwoom-Securities/Kiwoom-REST-API · PyPI kwcli kwcli 1.0.3 (2026-09) ≥ 3.13 Kiwoom's own license (use limited to Kiwoom OpenAPI) Specs for 337 APIs (Korean and US stocks), 362 per-function examples, Postman collection, kiwoomcli CLI, two MCP servers (spec search and execution; orders only when explicitly allowed)

Published by Kiwoom itself, so it is the closest thing to the source of truth for the API, and it covers US stocks. Read the comparison below knowing that it overlaps with these official tools.

OpenAPI+ (OCX) wrappers

Package Latest (uploaded) Python Notes
pykiwoom 0.1.6 (2024-01) not stated pywin32 + PyQt5. The most Korean tutorials
KOAPY 0.9.0 (2022-09) 3.8–3.10 Calls the OCX remotely through a gRPC server
kiwoom 1.5.0 (2025-08) 3.8–3.11 Thin PyQt5 wrapper

REST API wrappers

Package Latest (uploaded) Python License Features stated in its README
kiwoom-client (this project) see PyPI ≥ 3.10 MIT Same sync/async surface, auto token refresh, per-TR rate limiter, real-time WebSocket, MCP server with opt-in live orders
pykiwoom-rest 2.2.0 (2026-07) ≥ 3.8 (MCP ≥ 3.10) MIT Library + kiwoom CLI + MCP server, pandas output
kiwoom-cli / kiwoom-mcp 2.14.0 / 0.1.2 (2026-07) ≥ 3.10 own license / Apache-2.0 CLI first. MCP registers order tools only with --allow-orders; order pre-check and dry-run
kiwoompy 0.1.6 (2026-03) ≥ 3.12 MIT Attribute-style response models (balance.tot_evlt_amt), docs site
kiwoom-rest-api 0.1.12 (2025-06) ≥ 3.9 not stated Per-module classes + CLI

What kiwoom-client does differently

Only things you can check in the code and tests.

  • Endpoints counted from code. 182 REST endpoints, 4 condition-search calls and 19 real-time types across 15 modules; the endpoint reference is generated from the source, with Kiwoom's own api_id (ka10001, ...) next to every method.
  • Same surface for sync and async. KiwoomAPI and AsyncKiwoomAPI have the same modules and methods, so moving a script to asyncio.gather is not a rewrite.
  • Defaults for long-running bots. Tokens refresh before expiry and are reissued on 401. The rate limiter is a per-TR token bucket tuned to the measured limit (about 1 req/s, burst 2) and backs off and retries on 429.
  • Agents never see live orders by default. On the live server the built-in MCP server does not register its 12 order tools until KIWOOM_MCP_ALLOW_LIVE_ORDERS=true. On the mock server they are always available. If you use Kiwoom's official MCP server or plugin and also want the order content checked (amount and quantity caps, market buys, repeated submits, daily counts), pair it with the same author's Claude Code hook kiwoom-order-guard.
  • Responses you can compute with. to_dataframe() and to_number() turn "+70000" and "1,234,567" into numbers and keep codes with meaningful leading zeros as strings. round_to_tick() snaps limit prices to KRX ticks.
  • Typed. Ships py.typed; CI runs mypy.

When to pick something else

  • You mainly want a CLI to query and trade from the terminal: kiwoom-cli or pykiwoom-rest. kiwoom-client is a library plus an MCP server only.
  • You want attribute-style response models: look at kiwoompy. kiwoom-client returns Kiwoom's JSON as dicts and converts on request with to_dataframe().
  • You want tools maintained by Kiwoom itself, or the US-stock APIs: use the official repository and kwcli. kiwoom-client wraps the domestic (Korean) REST API only.
  • You depend on something only OpenAPI+ has: you may still need an OCX wrapper such as pykiwoom.
  • You are on Python 3.8 or 3.9: kiwoom-client needs 3.10+.

If you want an MIT-licensed pip install library for the domestic REST API with the same sync and async surface, and an MCP server from the same package, kiwoom-client fits.

If something here is wrong or a project is missing, open an issue and it will be fixed.

kiwoom-client is an unofficial open-source project, not affiliated with Kiwoom Securities.