kxt

kxt is an async Python SDK for Korea Exchange (KRX) equities, futures, and options, backed by the Korea Investment & Securities (KIS) OpenAPI. Documentation is written in Korean and published at https://pumpkinredbean.github.io/kxt/.

---

kxt는 한국거래소(KRX) 주식·선물·옵션을 비동기 파이썬으로 다루기 위한 SDK입니다. 현재는 KIS(한국투자증권) OpenAPI 어댑터 하나를 제공하며, 브로커 중립 DTO 계층 위에 얇게 얹혀 있습니다.

Audience

• 파이썬으로 KRX 데이터를 수집하거나 자동매매 코드를 작성하는 개발자
• ccxt 계열의 브로커 중립 인터페이스를 한국 시장에서 찾는 사용자
• 라이브러리 우선(runtime-free) SDK를 선호하는 사용자

Key features

• 비동기 전용 — async/await 기반, 이벤트 루프 친화적
• 브로커 중립 DTO — InstrumentRef, Bar, OrderBookSnapshot 등 정규화된 응답 타입 (입력은 종목 코드 문자열)
• 시세·주문·스트림 — get_bars, get_quote, submit_order, stream_trades 등 flat 메서드
• 얇은 CLI — 동일한 코드 경로를 kxt bars, kxt quote 같은 명령으로 호출

Import policy

• from kxt import ... — KISClient, 응답·이벤트 DTO, enum, 에러 등 사용자가 읽는 타입.
• from kxt.requests import ... — BarsRequest, SubmitOrderRequest, *Cursor, *Subscription, OrderInstruction, OrderAmendment, ProviderRef 같은 power-user 입력 DTO. 일반 호출은 primitive(symbol 문자열, kwargs)만으로 충분합니다.
• from kxt.models import ... — 모든 DTO를 통째로 introspection할 때.

Install

pip install --pre kxt

현재 알파 릴리스이므로 --pre 플래그가 필요합니다. 1.0 이후 해제됩니다.

Quick start

import asyncio
from datetime import date, timedelta

from kxt import KISClient


async def main() -> None:
    async with KISClient(
        app_key="<APP_KEY>",
        app_secret="<APP_SECRET>",
    ) as client:
        today = date.today()
        response = await client.get_bars(
            "005930",  # 삼성전자
            timeframe="day",
            start=today - timedelta(days=14),
            end=today,
        )
        for bar in response.bars[-5:]:
            print(bar.opened_at.date(), bar.close)


asyncio.run(main())

<APP_KEY> / <APP_SECRET>은 본인의 KIS OpenAPI 자격증명으로 대체하세요. SDK는 환경변수에 관여하지 않습니다. 환경변수 기반 흐름은 CLI에서만 사용합니다.

Documentation

전체 한국어 문서: https://pumpkinredbean.github.io/kxt/

• Getting Started — 설치, 인증, 5분 튜토리얼
• Unified API — 메서드 레퍼런스
• KIS Provider — 지원 매트릭스, TR_ID, 공식 링크
• Schemas — 공유 DTO
• CLI
• Architecture

로컬에서 빌드하려면:

uv sync --all-extras
uv run pytest
uv run mkdocs serve
uv build

Status

현재 알파(0.1.x alpha) 단계입니다. 공개 API는 1.0 이전까지 예고 없이 변경될 수 있습니다. 실거래 전에 반드시 소량으로 검증하세요.

License

MIT. LICENSE 참조.