Skip to content

FAQ

Getting started

Q. Is this Kiwoom's official library? No. It is an open-source (MIT) client unaffiliated with Kiwoom Securities. It wraps Kiwoom's published REST API as is, and field names and codes follow Kiwoom's official documentation and spec.

Q. Where do I get an app key? Apply for API use on the Kiwoom REST API portal to get an app key and secret. Paper-trading (모의투자) and live (실전투자) keys are different keys.

Q. What should I do first? Start with a paper-trading key.

from kiwoom_client import KiwoomAPI

api = KiwoomAPI.from_env(is_mock=True)  # KIWOOM_APP_KEY / KIWOOM_APP_SECRET
print(api.stock_info.basic_stock_info(stk_cd="005930")["stk_nm"])

is_mock defaults to False (the live server). Forgetting it with a paper key gives error 8030/8031 — see Troubleshooting.

Q. Does it need Windows or 32-bit Python? No. It is REST, so it runs on Windows, macOS and Linux with 64-bit Python 3.10+. There is no OCX or login window, so it runs on servers and in containers. Step by step: macOS and Linux.

Q. How do I port OpenAPI+ (KOA Studio) / pykiwoom code? What opt10081-style TRs, SendOrder and SetRealReg become in REST is in Migrating from OpenAPI+.

Usage

Q. How do I find the method for a TR (api_id)? Search the endpoint reference for the api_id (ka10081) or the Korean TR name. In code:

from kiwoom_client import spec

print([(t.api_id, t.name) for t in spec.search("일봉")])
print(spec.get("ka10081").required_fields)  # required request fields

Q. How do I pass request fields? As keyword arguments named exactly like Kiwoom's fields, with string values (stk_cd="005930", ord_qty="10"). Field lists are in the field reference and kiwoom_client.spec; common coded values have names in kiwoom_client.codes (OrderType.LIMIT, Exchange.KRX, …).

Q. Every value in the response is a string. That is how Kiwoom sends them ("+70000", "1,234"). Convert with to_dataframe() / normalize() / to_number(); stock codes and dates stay strings.

Q. Sync (KiwoomAPI) or async (AsyncKiwoomAPI)? Sync for simple scripts. Async when calling different TRs concurrently or alongside the WebSocket — asyncio recipe.

Q. What about continuation (next page)? If the response's "cont-yn" is "Y", call again with cont_yn="Y", next_key=resp["next-key"], or use request_all() — pagination recipe.

Q. Do I need to manage the token? No. It is issued on the first call, refreshed before it expires, and reissued (with one retry) if rejected. Measured on the live server, a token lasted about 18 hours, and reissuing within that time returned the same token (0.2.1 changelog).

Q. Should I call api.logout()? No need. logout() revokes the token, which can cut off other programs using the same app key. To just close connections, use api.close() or a with block.

Q. Rate limits? Kiwoom limits each TR (api_id) separately. The client paces each TR at 1 request/s with a burst of 2 and retries on 429 — rate-limit recipe.

Q. NXT / SOR? Put KRX, NXT or SOR in the order field dmst_stex_tp. Quote and chart TRs take stock codes like 005930_NX / 005930_AL per the official spec; kiwoom_client.codes.exchange_stock_code("005930", "NXT") builds them. Paper trading supports KRX only.

Q. Overseas stocks? This library wraps the domestic-stock API only (182 REST endpoints + condition search + real-time). Gold-spot quote and order TRs are included.

Orders and safety

Q. Is it safe to run order code? With is_mock=True it talks to the paper-trading server and nothing really fills. With is_mock=False (the default), api.order.* and api.credit_order.* place real orders on a real account. Nothing in the Python API blocks them, so add your own quantity/price checks before going live.

Q. My limit order is rejected. A price that is not a multiple of the tick size is rejected or repriced. Use round_to_tick() — limit-order recipe.

AI agents and MCP

Q. Can I use it from Claude Code or Cursor? Two ways: ① the MCP server (pip install 'kiwoom-client[mcp]', kiwoom-client-mcp) exposes the endpoints as tools; ② rules and a skill that help an AI write code with this library (llms.txt, AGENTS.md, a Claude Code skill, Cursor and Copilot rules) — Using it from AI coding tools.

Q. Can an AI place live orders through MCP on its own? On a live account (KIWOOM_IS_MOCK=false) the order tools are not even registered until you set KIWOOM_MCP_ALLOW_LIVE_ORDERS=true yourself. In paper trading they are always available.

Other

Q. Does it work without pandas? Yes. Only to_dataframe() needs pandas (pip install 'kiwoom-client[pandas]').

Q. Where do bugs and requests go? GitHub Issues. Usage questions go to Discussions. Remove keys and account numbers first.