Real-time trades and order book over WebSocket¶
Real-time quotes come over a single WebSocket, not REST. The steps are always the same:
create_websocket() → connect() (through LOGIN) → on(type, callback) → subscribe(type, codes) → listen().
| Type | Name | Common FIDs (keys of values) |
|---|---|---|
0B |
Stock trade (주식체결) | 20 trade time, 10 current price, 15 volume (+buy/−sell), 13 cumulative volume, 12 change rate, 228 execution strength |
0D |
Order book (주식호가잔량) | 21 quote time, 41–50 ask 1–10, 51–60 bid 1–10, 61/71 ask/bid quantity 1 |
0C |
Best bid/ask (주식우선호가) | 27 (best) ask, 28 (best) bid |
FID names follow Kiwoom's official REST spec; all types are in the real-time section of the endpoint reference.
Receive trades and keep the last price¶
import asyncio
from kiwoom_client import KiwoomAPI, to_number
last_price: dict[str, int] = {}
def on_trade(d: dict) -> None:
v = d["values"]
price = abs(to_number(v.get("10", "0"))) # the sign is the direction vs. the previous close
last_price[d["item"]] = price
print(f"{v.get('20')} {d['item']} {price:>9,} volume {v.get('15')}")
async def main():
api = KiwoomAPI.from_env(is_mock=True)
ws = api.create_websocket()
await ws.connect() # KiwoomWebSocketError if LOGIN fails
ws.on("0B", on_trade)
await ws.subscribe("0B", ["005930", "000660"])
listener = asyncio.create_task(ws.listen()) # listen() answers PING, reconnects, restores subscriptions
await asyncio.sleep(60) # receive for one minute
await ws.disconnect() # then stop
await listener
print(last_price)
asyncio.run(main())
The order book on the same socket¶
import asyncio
from kiwoom_client import KiwoomAPI
def on_book(d: dict) -> None:
v = d["values"]
print(d["item"], "ask1", v.get("41"), "x", v.get("61"), "| bid1", v.get("51"), "x", v.get("71"))
async def main():
api = KiwoomAPI.from_env(is_mock=True)
async with api.create_websocket() as ws: # disconnect() on exit
ws.on("0D", on_book)
await ws.subscribe(["0B", "0D"], "005930")
await ws.listen()
asyncio.run(main())
- Callbacks can be plain functions or
async def. If a callback raises, the other callbacks and receiving keep going (the error is logged). subscribe(..., refresh="1")(the default) keeps existing registrations and adds to them. With"0"it clears the existing registrations and keeps only this one.- To remove a registration,
await ws.unsubscribe("0B", "005930"). - To see every frame,
ws.on_message(callback)— when a REAL frame arrives you get the wholedatalist. - The field names of the items (
item/values) match the official spec's example, but this library has not yet confirmed them on the live server during market hours (the "Verification status" note in the README). If something looks off, please open an issue.