# kiwoom-client > Python client for the Kiwoom Securities (키움증권) REST API and real-time WebSocket: 182 REST endpoints, 4 condition-search calls and 19 real-time types, sync (`KiwoomAPI`) and asyncio (`AsyncKiwoomAPI`) facades, automatic token refresh, per-TR rate limiting, response parsing to numbers/DataFrames, KRX tick sizes, and a built-in MCP server. REST, not OCX/COM — runs on Windows, macOS and Linux. Install `pip install kiwoom-client` (extras `[pandas]`, `[mcp]`), Python 3.10+, import name `kiwoom_client`. Keys come from the Kiwoom REST API portal (https://openapi.kiwoom.com). Rules for writing code against this library: - `KiwoomAPI(app_key, app_secret, is_mock=False)` — **`is_mock` defaults to `False`, the live server.** Pass `is_mock=True` for paper trading (모의투자, mockapi.kiwoom.com). Live and paper keys are different; a key used against the wrong server is rejected (Kiwoom error 8030/8031, raised as `KiwoomServerMismatchError`). - `KiwoomAPI.from_env(is_mock=True)` reads `KIWOOM_APP_KEY` / `KIWOOM_APP_SECRET` / `KIWOOM_IS_MOCK` (the same variables as the MCP server). Never hard-code or print keys. - `api.order.*` and `api.credit_order.*` place **real, irreversible orders** when `is_mock=False`. Nothing in the Python API blocks them; only the MCP server has an opt-in guard (`KIWOOM_MCP_ALLOW_LIVE_ORDERS`). Do not run order code against a live account unless the user explicitly asks. - `api.logout()` revokes the access token. Other processes sharing the same app key may lose their session — do not call it casually. - Every REST method has the same signature `(cont_yn="N", next_key="", **fields)`. Pass Kiwoom's own request field names as keyword arguments with **string** values (`stk_cd="005930"`, `ord_qty="10"`). Find the method for an api_id (`ka10081`) or a Korean TR name in the endpoint reference; look fields up with `kiwoom_client.spec.get("ka10081").required_fields` or Kiwoom's guide. Do not invent method names. - Coded fields have named constants in `kiwoom_client.codes` (`OrderType.LIMIT`, `Exchange.KRX`, …). - Responses are plain dicts whose values are strings (`"+70000"`, `"1,234"`). `to_dataframe()` / `normalize()` / `to_number()` convert them; codes and dates stay strings. A non-zero `return_code` raises `KiwoomAPIError(code, message, response)` or one of its subclasses in `kiwoom_client.errors`. - Continuation: a response carries `"cont-yn"` and `"next-key"`; call again with `cont_yn="Y", next_key=...`, or use `api._client.request_all(url, api_id, body)`. - Rate limits are per api_id (about 1 req/s, burst 2) and handled by the client; different api_ids run concurrently under `AsyncKiwoomAPI`. - Limit prices must be on the KRX tick grid: `round_to_tick(price)`. - Real-time: `ws = api.create_websocket()`, `await ws.connect()`, `ws.on("0B", cb)`, `await ws.subscribe("0B", "005930")`, `await ws.listen()`. `values` keys are Kiwoom FID numbers (`"10"` = current price). ## Docs - [Endpoint reference](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/docs/endpoints.md): every REST method with api_id, URL and Korean/English TR name; condition search; real-time types - [README (English)](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/README_EN.md): install, quick start, accounts and orders, asyncio, DataFrame parsing, WebSocket, pagination, rate limits, MCP server - [README (한국어)](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/README.md): the same, in Korean - [AGENTS.md](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/AGENTS.md): rules for AI agents using or working on this library: safety, lookups, tests - [Migrating from OpenAPI+ (OCX) / pykiwoom](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/docs/migration-from-openapi-plus.md): OpenAPI+ functions, SendOrder codes, real-time types and TR codes mapped to REST - [Cookbook (한국어)](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/docs/cookbook/index.md): runnable paper-trading recipes: daily candles to DataFrame, pagination, balances, asyncio, tick-aligned limit orders, WebSocket trades, real-time condition search, rate limits - [FAQ](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/docs/faq.en.md): keys, paper vs live, finding methods and fields, tokens, rate limits, NXT/SOR, orders, MCP - [Troubleshooting](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/docs/troubleshooting.en.md): error codes (8030/8031 paper-vs-live key, 8005 token, 1700 rate limit, 15xx fields, 19xx stock codes), exception classes and fixes - [Using it from AI coding tools](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/docs/ai-tools.en.md): llms.txt, AGENTS.md, the Claude Code skill/plugin and how to install them ## Optional - [Agent Skill](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/skills/kiwoom-client/SKILL.md): the same rules as a Claude Code / Agent Skills skill, with examples - [llms-full.txt](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/llms-full.txt): public API signatures and docstrings plus the full endpoint list in one file - [Changelog](https://raw.githubusercontent.com/younghwan91/kiwoom-client/main/CHANGELOG.md): release history - [Kiwoom REST API guide (official)](https://openapi.kiwoom.com/guide/apiguide): request/response field definitions for each api_id - [Kiwoom REST API spec (official GitHub)](https://github.com/Kiwoom-Securities/Kiwoom-REST-API): machine-readable spec and error codes