kis-trader 0.1.0__tar.gz

kis_trader-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "kis-trader",
+  "interface": { "displayName": "KIS Trader" },
+  "plugins": [
+    {
+      "name": "kis-trader",
+      "version": "0.0.0",
+      "description": "Playbook skill for driving the kis_trader KIS Open API client under its safety-kernel discipline.",
+      "source": { "source": "local", "path": "./plugins/kis-trader" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Productivity"
+    }
+  ]
+}

kis_trader-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "version": "1",
+  "name": "kis-trader",
+  "owner": { "name": "seokhoonj" },
+  "description": "Drive the kis_trader Korea Investment & Securities (KIS) Open API client under its safety-kernel discipline",
+  "plugins": [
+    {
+      "name": "kis-trader",
+      "displayName": "KIS Trader",
+      "source": "./plugins/kis-trader",
+      "description": "Playbook skill for driving the kis_trader KIS Open API client under its safety-kernel discipline (search-before-trade, ticket confirmation, reconcile-not-resend).",
+      "author": { "name": "seokhoonj" },
+      "homepage": "https://github.com/seokhoonj/kis-trader",
+      "category": "Productivity",
+      "keywords": ["kis", "korea-investment", "trading", "stocks", "open-api", "korean-stocks"]
+    }
+  ]
+}

kis_trader-0.1.0/.github/workflows/check.yml

@@ -0,0 +1,24 @@
+name: check
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+
+# A newer push to the same branch or PR makes the older run's result obsolete,
+# so cancel it rather than let both run to completion.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# The check only reads the code to lint, type, and test it -- it never writes to the
+# repo -- so it runs with the least privilege that still allows a checkout.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    # The full check lives in reusable-check.yml so the release gate in
+    # publish.yml runs the identical job on the release commit.
+    uses: ./.github/workflows/reusable-check.yml

kis_trader-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,71 @@
+name: publish
+
+# Publish to PyPI on a GitHub Release, via PyPI Trusted Publishing (OIDC): no API
+# token or password is stored anywhere -- GitHub mints a short-lived identity token
+# that PyPI verifies against the publisher registered for this repo (owner seokhoonj
+# / repo kis-trader / this workflow / environment "pypi").
+#
+# Three jobs. `gate` runs the same reusable check that check.yml runs, on the
+# release commit, so a red build (a lint/type error, a broken test, a lost py.typed
+# or console script) cannot reach an upload. `build` builds the sdist and wheel and
+# hands them to `publish` as an artifact. `publish` -- the only job holding the OIDC
+# token -- downloads that artifact and uploads it, and checks out no source, so the
+# privileged step runs the least code.
+
+on:
+  release:
+    types: [published]
+
+# Workflow-level floor: any job without its own `permissions:` block still gets a
+# read-only token, so a job added later cannot silently inherit a write-capable
+# default. The build and publish jobs narrow it further below.
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    uses: ./.github/workflows/reusable-check.yml
+
+  build:
+    needs: gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Assert the release tag matches the package version
+        # A release tagged v0.2.0 while pyproject still says 0.1.0 would publish the wrong
+        # version -- and a PyPI version number can never be reused. Fail before the build.
+        # The tag is passed through env, never interpolated into the script, so a crafted
+        # tag name cannot inject shell.
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "${TAG#v}" = "$version" || { echo "release tag '$TAG' does not match package version '$version'"; exit 1; }
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: Build sdist and wheel, then check the metadata
+        run: |
+          uv build
+          uvx twine check dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC; this is what replaces a stored token
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1

kis_trader-0.1.0/.github/workflows/reusable-check.yml

@@ -0,0 +1,108 @@
+name: reusable check
+
+# The full check -- tests, lint, types, and the packaging assertions -- factored
+# into one reusable job so both `check.yml` (on push / PR) and the release gate in
+# `publish.yml` run the *identical* thing. One definition is what makes "publish
+# gates on the full check" true; a second hand-maintained copy would drift, and a
+# check added here silently would not gate releases.
+
+on:
+  workflow_call:
+
+# The floor lives on the shared body, not only on `check.yml`: `publish.yml`'s gate
+# calls this same workflow, and if the floor were only on `check.yml` the gate would
+# run this check with the repo-default (possibly write) token. Declared here, the
+# check is read-only from every caller. A reusable workflow can only downscope from
+# the caller, so this never widens anyone's token.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # Every version the unbounded requires-python (>=3.11) actually claims, through
+        # the current stable release. 3.11 is the floor that claim has to hold on.
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+
+      - name: Install
+        # A venv per matrix version, not `uv pip --system`: the runner's system
+        # Python is externally managed and is one fixed version whatever the matrix
+        # says. This is also what the docs tell a person to run.
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev]"
+          .venv/bin/python -c "import sys; print('testing on', sys.version)"
+
+      - name: Test
+        run: .venv/bin/pytest -q
+
+      - name: Lint
+        run: .venv/bin/ruff check src tests
+
+      - name: Type check
+        run: .venv/bin/mypy
+
+      - name: Type check narrowing fixtures
+        run: .venv/bin/mypy --strict tests/typing
+
+      - name: Confirm the runtime dependencies are exactly the declared three
+        # The three-dependency claim is documented in the pyproject comment; a claim
+        # nothing checks quietly stops being true. Installed into a bare environment,
+        # kis_trader must import with nothing beyond requests, websockets, and
+        # cryptography present.
+        run: |
+          uv venv /tmp/bare --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/bare/bin/python .
+          /tmp/bare/bin/python -c "
+          import re
+          import importlib.metadata as md
+          requires = md.requires('kis-trader') or []
+          runtime = [r for r in requires if 'extra ==' not in r]
+          # Extract each requirement's bare name (before any version/marker/extra) and
+          # normalize to PEP 503 form; the runtime set must be exactly the declared
+          # three, so a fourth dependency slipping in fails here.
+          names = sorted(re.split(r'[<>=!~;\[\s]', r, 1)[0].replace('_', '-').lower() for r in runtime)
+          assert names == ['cryptography', 'requests', 'websockets'], f'unexpected runtime dependencies: {runtime}'
+          import kis_trader
+          print('kis_trader imports with only the declared runtime dependencies present')
+          "
+          # The console script runs, and its top-level --version prints (not shoved
+          # into a required subcommand).
+          /tmp/bare/bin/kis --version
+
+      - name: Confirm a user's type checker can see the hints
+        # Every hint in this package is invisible to a user unless py.typed ships
+        # alongside it (PEP 561), and the source cannot answer whether it did:
+        # src/kis_trader/py.typed can sit in git while the built wheel omits it. So ask
+        # it the way a user does -- install the built package into a clean environment
+        # and run their checker over their code.
+        run: |
+          uv venv /tmp/typed --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/typed/bin/python . mypy
+          cat > /tmp/user_code.py <<'PY'
+          from kis_trader import KISClient
+
+          # profile is str | None; an int is neither, so a checker that can see the
+          # shipped hints must reject it and name the expected type.
+          KISClient(profile=123)
+          PY
+          # The checker MUST reject the call (a pass would mean it saw no hints); then
+          # assert the specific arg-type diagnostic, not just any line containing "str".
+          if /tmp/typed/bin/mypy /tmp/user_code.py > /tmp/mypy_out 2>&1; then
+            cat /tmp/mypy_out
+            echo "mypy accepted KISClient(profile=123) -- shipped hints are not visible"
+            exit 1
+          fi
+          cat /tmp/mypy_out
+          grep -Fq 'Argument "profile" to "KISClient" has incompatible type "int"' /tmp/mypy_out
+          grep -Fq '[arg-type]' /tmp/mypy_out

kis_trader-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# AI coding agents
+CLAUDE.md
+.claude/
+AGENTS.md
+AGENT.md
+.codex/
+GEMINI.md
+.gemini/
+
+dev/
+refs/
+
+# Local reference clones and tooling (not part of the package)
+python-kis/
+kis-agent/
+kis-ai-ext/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+build/
+uv.lock
+
+# Docs build output (Quarto)
+docs/_site/
+docs/.quarto/
+docs/objects.json
+docs/reference/
+
+.superpowers/

kis_trader-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 — 2026-10-02
+
+First public release.
+
+- Typed Python client for the Korea Investment & Securities (KIS) Open API —
+  domestic and overseas quotes, orders, and account views (`kis.domestic`,
+  `kis.overseas`, `kis.account`, `kis.orders`).
+- Order safety core: an idempotent order store (dedup by client order id and
+  fingerprint), fail-closed `RiskLimits`, and a `reconcile` path for orders whose
+  outcome is unclear.
+- Real-time WebSocket subscriptions for quotes, order books, and fills.
+- Optional MCP server (`pip install 'kis-trader[mcp]'`, console script `kis-mcp`)
+  exposing the safe read surface plus a dry-run order preview and reconcile.
+- English public identifiers with Korean docstrings; ships `py.typed`.

kis_trader-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seokhoon Joo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kis_trader-0.1.0/Makefile

@@ -0,0 +1,13 @@
+# Run the standard CI checks (test, lint, types) locally. Dev extras: uv pip install -e ".[dev]"
+.PHONY: check test lint types
+
+check: test lint types
+
+test:
+	pytest -q
+
+lint:
+	ruff check src tests
+
+types:
+	mypy

kis_trader-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: kis-trader
+Version: 0.1.0
+Summary: A clean Python client for the Korea Investment & Securities (KIS) Open API (English identifiers, Korean docstrings for KIS users)
+Author-email: Seokhoon Joo <seokhoonj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: requests>=2.31
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: mcp>=2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# kis-trader
+
+[![check](https://github.com/seokhoonj/kis-trader/actions/workflows/check.yml/badge.svg)](https://github.com/seokhoonj/kis-trader/actions/workflows/check.yml)
+[![PyPI](https://img.shields.io/pypi/v/kis-trader)](https://pypi.org/project/kis-trader/)
+[![Python](https://img.shields.io/pypi/pyversions/kis-trader)](https://pypi.org/project/kis-trader/)
+[![License](https://img.shields.io/pypi/l/kis-trader)](https://github.com/seokhoonj/kis-trader/blob/main/LICENSE)
+
+**한국어** | [English](README.en.md)
+
+한국투자증권 **KIS Open API**의 비공식 파이썬 클라이언트.
+
+국내·해외 주식과 지수, ETF·ETN, ELW, 선물·옵션, 채권의 시세와 재무·수급, 계좌 잔고와 손익,
+순위·조건검색, 시장·일정, 퇴직연금, 그리고 매수·매도·정정·취소 주문까지 다룹니다. 실시간
+시세·체결통보(WebSocket)와 터미널 명령 `kis` 도 함께 제공합니다.
+
+## 1. 설치
+
+```bash
+pip install kis-trader
+```
+
+파이썬 3.11 이상이 필요합니다. 소스에서 개발 설치하려면 `uv pip install -e .` 를 쓰세요.
+
+## 2. 빠른 시작
+
+```python
+from kis_trader import KISClient
+
+kis = KISClient(app_key="…", app_secret="…", account="12345678-01")
+
+kis.domestic.stock("005930").quote()                 # 삼성전자 현재가
+kis.overseas.stock("AAPL").quote()                   # 애플 (거래소 자동 판별)
+kis.domestic.ranking.by_change(direction="gainers")  # 오늘 상승률 순위
+```
+
+앱키와 계좌는 환경변수나 `KISConfig(...).save()` 로 한 번 저장해 두면 이후 인자 없이 열 수
+있습니다. 발급과 저장은 [자격증명과 프로필](https://seokhoonj.github.io/kis-trader/configuration.html)
+문서를 참고하세요.
+
+## 3. 구조
+
+`KISClient` 아래로 자산군과 주문이 네임스페이스로 나뉩니다.
+
+```python
+kis.domestic   # 국내: 주식·지수·ETF·ELW·선물옵션·채권·계좌·순위·시장·일정
+kis.overseas   # 해외: 주식·지수·선물옵션·계좌·순위
+kis.account    # 계좌 조회 (상품코드 자동 분기; IRP는 .pension 퇴직연금 조회)
+kis.orders     # 접수한 주문의 조회(미체결)·확인·정정·취소
+```
+
+종목과 계약은 핸들로 잡아 시세 조회부터 주문까지 이어갑니다.
+
+```python
+kis.domestic.stock("005930")     # 국내 주식 -- 현재가·차트·호가·매수·매도
+kis.overseas.stock("AAPL")       # 해외 주식 -- 거래소 자동 판별
+kis.domestic.futures("101W09")   # 지수선물
+kis.domestic.option("201W09")    # 지수옵션
+```
+
+## 4. 주문
+
+```python
+r = kis.domestic.stock("005930").buy(quantity=10, limit_price=70000)  # 10주 매수
+kis.orders.reconcile(r.client_order_id)   # 실제 접수 여부를 증권사에 재확인
+kis.orders.cancel(r.client_order_id)      # 취소
+```
+
+주문은 되돌릴 수 없습니다. 중복 주문을 막는 안전장치가 기본으로 동작하고(신용거래는 기본
+차단), 자세한 규칙은 [주문 문서](https://seokhoonj.github.io/kis-trader/orders.html)에 있습니다.
+
+## 5. 명령줄 (`kis`)
+
+설치하면 터미널 명령 `kis` 가 함께 깔립니다. 파이썬을 짜지 않고도 조회와 주문을 할 수 있습니다.
+주문은 `--execute` 를 붙이기 전까지 실제로 전송되지 않는 실행 안 함(dry-run) 상태입니다.
+
+```bash
+kis stock quote 005930
+kis search 삼성전자
+kis ranking change --direction gainers
+kis account balance
+kis order buy 005930 10 --limit-price 70000                       # 실행 안 함(dry-run)
+kis order buy 005930 10 --limit-price 70000 --execute paper --yes  # 모의투자로 실제 전송
+kis account balance --asset bond                                  # 채권 lot 목록(buy_date/buy_sequence 컬럼)
+kis order buy KR6449111CB8 100 --asset bond --limit-price 10125    # 채권 매수(dry-run)
+# 채권 매도는 목록의 buy_sequence 컬럼을 --buy-seq 로, buy_date 를 --buy-date 로 지목한다:
+kis order sell KR6449111CB8 100 --asset bond --limit-price 10130 --buy-date 20260814 --buy-seq 1
+kis account orders --asset bond --date 20260814                   # 채권 미체결 확인(주문 타임아웃 후)
+kis account fills --start 20240101 --end 20240131                 # 국내주식 체결내역(기간)
+kis account profits --start 20240101 --end 20240131               # 국내 종목별 실현손익
+kis account transactions --venue overseas --start 20240101 --end 20240131  # 해외 거래·입출금내역
+kis --profile futures account balance                             # 선물옵션 계좌(프로필 03/08)
+kis --profile futures account deposit                             # 선물옵션 예수금현황
+kis account fills --asset bond --start 20240101 --end 20240131    # 채권 체결내역(기간)
+kis order buy 005930 10 --limit-price 70000 --reserve --end-date 20260901   # 예약매수(실전전용)
+kis account reserved --start 20260101 --end 20260901              # 예약주문 목록
+kis order cancel-reserved <순번> --order-date 20260901              # 예약 취소
+kis order modify-reserved <순번> --symbol 005930 --side buy --quantity 10 --limit-price 71000  # 예약 정정(전체 재지정; 단가 생략 시 시장가)
+kis order twap 005930 --side buy --quantity 100 --over 30m --slices 3   # 국내 TWAP 분할(30분간 3회 시장가; dry-run)
+kis order buy 00700 100 --venue overseas --reserve --limit-price 350 --exchange HKS --currency HKD  # 해외 예약매수(지정가 필수; 통화는 홍콩 전용; 모의 허용)
+kis account reserved --venue overseas --start 20260101 --end 20260901  # 해외 예약주문 목록(미국+아시아)
+kis order cancel-reserved US123 --venue overseas --receipt-date 20260901  # 해외 예약 취소(미국 전용; 아시아는 kis order cancel)
+kis order buy AAPL 10 --venue overseas --limit-price 150 --algo twap --execute real --yes  # 미국 algo 분할(twap/vwap; 실전·최소 10주)
+kis order buy 101W09 1 --asset futures --limit-price 350.5        # 국내 선물 지정가
+kis order buy 201S07 1 --asset option --right call --limit-price 5.2  # 국내 옵션
+kis order buy <sym> 1 --asset futures --venue overseas --limit-price 100  # 해외 선물
+```
+
+## 6. AI 코딩 에이전트에서 사용
+
+Claude Code·Codex 같은 AI 도구로 계좌를 다루려면 `plugins/kis-trader/skills/kis-trader/` 스킬을 씁니다.
+[Claude 스킬](https://seokhoonj.github.io/kis-trader/claude-skill.html) ·
+[Codex 스킬](https://seokhoonj.github.io/kis-trader/codex-skill.html) 문서를 참고하세요.
+
+MCP 호환 에이전트(Claude Desktop 등)에는 `kis_trader.mcp` 서버(`pip install 'kis-trader[mcp]'` 후
+`kis-mcp`)로 계좌 조회·주문 미리보기 도구를 열 수 있습니다(실주문 전송은 노출하지 않음).
+[MCP 서버](https://seokhoonj.github.io/kis-trader/mcp.html) 문서를 참고하세요.
+
+## 7. 문서
+
+전체 문서는 **<https://seokhoonj.github.io/kis-trader/>** 에 있습니다(소스: `docs/`).
+
+| 파트 | 장 |
+|------|----|
+| **시작하기** | [빠른 시작](https://seokhoonj.github.io/kis-trader/quickstart.html) · [앱키 발급](https://seokhoonj.github.io/kis-trader/appkey.html) · [자격증명과 프로필](https://seokhoonj.github.io/kis-trader/configuration.html) |
+| **국내 주식** | [시세](https://seokhoonj.github.io/kis-trader/quotes.html) · [재무·실적](https://seokhoonj.github.io/kis-trader/financials.html) · [종목 수급](https://seokhoonj.github.io/kis-trader/flows.html) · [계좌·손익](https://seokhoonj.github.io/kis-trader/account.html) · [주문](https://seokhoonj.github.io/kis-trader/orders.html) |
+| **시장·검색** | [순위·조건검색](https://seokhoonj.github.io/kis-trader/screening.html) · [시장·지수](https://seokhoonj.github.io/kis-trader/market.html) · [기업행위·일정](https://seokhoonj.github.io/kis-trader/corporate-actions.html) |
+| **해외·연금** | [해외주식](https://seokhoonj.github.io/kis-trader/overseas.html) · [퇴직연금](https://seokhoonj.github.io/kis-trader/pension.html) |
+| **다른 상품** | [ETF·ETN](https://seokhoonj.github.io/kis-trader/etf.html) · [ELW](https://seokhoonj.github.io/kis-trader/elw.html) · [선물·옵션](https://seokhoonj.github.io/kis-trader/derivatives.html) · [채권](https://seokhoonj.github.io/kis-trader/bonds.html) |
+| **명령줄·에이전트** | [Command Line](https://seokhoonj.github.io/kis-trader/cli.html) · [Claude Skill](https://seokhoonj.github.io/kis-trader/claude-skill.html) · [Codex Skill](https://seokhoonj.github.io/kis-trader/codex-skill.html) · [MCP Server](https://seokhoonj.github.io/kis-trader/mcp.html) |
+| **참고** | [실시간(WebSocket)](https://seokhoonj.github.io/kis-trader/realtime.html) · [한계·미구현](https://seokhoonj.github.io/kis-trader/limits.html) |
+
+각 메서드의 인자와 반환값은 `help(그_메서드)` 로 바로 볼 수 있습니다.
+
+## 8. 라이선스
+
+[MIT](LICENSE)

kis_trader-0.1.0/README.en.md

@@ -0,0 +1,135 @@
+# kis-trader
+
+[![check](https://github.com/seokhoonj/kis-trader/actions/workflows/check.yml/badge.svg)](https://github.com/seokhoonj/kis-trader/actions/workflows/check.yml)
+[![PyPI](https://img.shields.io/pypi/v/kis-trader)](https://pypi.org/project/kis-trader/)
+[![Python](https://img.shields.io/pypi/pyversions/kis-trader)](https://pypi.org/project/kis-trader/)
+[![License](https://img.shields.io/pypi/l/kis-trader)](https://github.com/seokhoonj/kis-trader/blob/main/LICENSE)
+
+[한국어](README.md) | **English**
+
+An unofficial Python client for the Korea Investment & Securities (KIS) **Open API**.
+
+Domestic and overseas stocks and indices, ETFs and ETNs, ELWs, futures and options, and bonds —
+their quotes, financials and flows, account balances and profit, rankings and conditional
+screens, market data and calendars, retirement pensions, and buy/sell/modify/cancel orders. Live
+quotes and execution notices (WebSocket) and a terminal command `kis` come with it.
+
+## 1. Install
+
+```bash
+pip install kis-trader
+```
+
+Requires Python 3.11+. For a development install from source, use `uv pip install -e .`.
+
+## 2. Quickstart
+
+```python
+from kis_trader import KISClient
+
+kis = KISClient(app_key="…", app_secret="…", account="12345678-01")
+
+kis.domestic.stock("005930").quote()                 # Samsung Electronics quote
+kis.overseas.stock("AAPL").quote()                   # Apple (exchange resolved automatically)
+kis.domestic.ranking.by_change(direction="gainers")  # today's top gainers
+```
+
+Save the app key and account once as environment variables or with `KISConfig(...).save()`, and
+later calls open without arguments. For issuing and storing credentials, see the
+[Credentials and profiles](https://seokhoonj.github.io/kis-trader/configuration.html) chapter.
+
+## 3. Structure
+
+Under `KISClient`, asset classes and orders split into namespaces.
+
+```python
+kis.domestic   # domestic: stocks, indices, ETFs, ELWs, futures/options, bonds, account, rankings, market, calendar
+kis.overseas   # overseas: stocks, indices, futures/options, account, rankings
+kis.account    # account queries (dispatched by product code; IRP adds .pension)
+kis.orders     # list (open), check, modify, and cancel submitted orders
+```
+
+Reach a symbol or contract through a handle, then read quotes and place orders from it.
+
+```python
+kis.domestic.stock("005930")     # domestic stock -- quote, chart, order book, buy, sell
+kis.overseas.stock("AAPL")       # overseas stock -- exchange resolved automatically
+kis.domestic.futures("101W09")   # index futures
+kis.domestic.option("201W09")    # index options
+```
+
+## 4. Orders
+
+```python
+r = kis.domestic.stock("005930").buy(quantity=10, limit_price=70000)  # buy 10 shares
+kis.orders.reconcile(r.client_order_id)   # re-check with the broker whether it was actually accepted
+kis.orders.cancel(r.client_order_id)      # cancel
+```
+
+Orders cannot be undone. A duplicate-order safeguard is on by default (credit trading is blocked
+by default); the full rules are in the [Orders](https://seokhoonj.github.io/kis-trader/orders.html)
+chapter.
+
+## 5. Command line (`kis`)
+
+Installing also adds the terminal command `kis`, so you can query and order without writing
+Python. An order is not actually sent until you add `--execute` — until then it is a dry run.
+
+```bash
+kis stock quote 005930
+kis search 삼성전자
+kis ranking change --direction gainers
+kis account balance
+kis order buy 005930 10 --limit-price 70000                       # dry run, not sent
+kis order buy 005930 10 --limit-price 70000 --execute paper --yes  # sent to paper trading
+kis account balance --asset bond                                  # list bond lots (buy_date/buy_sequence columns)
+kis order buy KR6449111CB8 100 --asset bond --limit-price 10125    # bond buy (dry run)
+# bond sell targets a lot: pass the buy_sequence column as --buy-seq, buy_date as --buy-date:
+kis order sell KR6449111CB8 100 --asset bond --limit-price 10130 --buy-date 20260814 --buy-seq 1
+kis account orders --asset bond --date 20260814                   # bond open orders (after an order timeout)
+kis account fills --start 20240101 --end 20240131                 # domestic stock fills history (range)
+kis account profits --start 20240101 --end 20240131               # domestic realized P&L by symbol
+kis account transactions --venue overseas --start 20240101 --end 20240131  # overseas transactions/cash ledger
+kis --profile futures account balance                             # futures/options account (03/08 profile)
+kis --profile futures account deposit                             # futures/options deposit snapshot
+kis account fills --asset bond --start 20240101 --end 20240131    # bond fills history (range)
+kis order buy 005930 10 --limit-price 70000 --reserve --end-date 20260901   # reserved buy (real only)
+kis account reserved --start 20260101 --end 20260901              # reserved orders list
+kis order cancel-reserved <seq> --order-date 20260901             # cancel a reservation
+kis order modify-reserved <seq> --symbol 005930 --side buy --quantity 10 --limit-price 71000  # modify a reservation (full re-specify; omit price -> market)
+kis order twap 005930 --side buy --quantity 100 --over 30m --slices 3   # domestic TWAP split (3 market slices over 30m; dry run)
+kis order buy 00700 100 --venue overseas --reserve --limit-price 350 --exchange HKS --currency HKD  # overseas reserved buy (limit only; currency is HK-only; paper allowed)
+kis account reserved --venue overseas --start 20260101 --end 20260901  # overseas reserved orders (US + Asia)
+kis order cancel-reserved US123 --venue overseas --receipt-date 20260901  # cancel overseas reservation (US only; Asia via kis order cancel)
+kis order buy AAPL 10 --venue overseas --limit-price 150 --algo twap --execute real --yes  # US server-side algo split (twap/vwap; real, min 10 shares)
+kis order buy 101W09 1 --asset futures --limit-price 350.5        # domestic futures (limit)
+kis order buy 201S07 1 --asset option --right call --limit-price 5.2  # domestic option
+kis order buy <sym> 1 --asset futures --venue overseas --limit-price 100  # overseas futures
+```
+
+## 6. Use it from an AI coding agent
+
+To manage an account through an AI tool such as Claude Code or Codex, use the
+`plugins/kis-trader/skills/kis-trader/` skill. See the
+[Claude skill](https://seokhoonj.github.io/kis-trader/claude-skill.html) and
+[Codex skill](https://seokhoonj.github.io/kis-trader/codex-skill.html) chapters.
+
+## 7. Documentation
+
+The full documentation lives at **<https://seokhoonj.github.io/kis-trader/>** (source: `docs/`).
+
+| Part | Chapters |
+|------|----------|
+| **Getting started** | [Quickstart](https://seokhoonj.github.io/kis-trader/quickstart.html) · [Issue an app key](https://seokhoonj.github.io/kis-trader/appkey.html) · [Credentials and profiles](https://seokhoonj.github.io/kis-trader/configuration.html) |
+| **Domestic stocks** | [Quotes](https://seokhoonj.github.io/kis-trader/quotes.html) · [Financials](https://seokhoonj.github.io/kis-trader/financials.html) · [Flows](https://seokhoonj.github.io/kis-trader/flows.html) · [Account & profit](https://seokhoonj.github.io/kis-trader/account.html) · [Orders](https://seokhoonj.github.io/kis-trader/orders.html) |
+| **Market & search** | [Rankings & screens](https://seokhoonj.github.io/kis-trader/screening.html) · [Market & indices](https://seokhoonj.github.io/kis-trader/market.html) · [Corporate actions & calendar](https://seokhoonj.github.io/kis-trader/corporate-actions.html) |
+| **Overseas & pension** | [Overseas stocks](https://seokhoonj.github.io/kis-trader/overseas.html) · [Retirement pension](https://seokhoonj.github.io/kis-trader/pension.html) |
+| **Other products** | [ETF & ETN](https://seokhoonj.github.io/kis-trader/etf.html) · [ELW](https://seokhoonj.github.io/kis-trader/elw.html) · [Futures & options](https://seokhoonj.github.io/kis-trader/derivatives.html) · [Bonds](https://seokhoonj.github.io/kis-trader/bonds.html) |
+| **CLI & agents** | [Command Line](https://seokhoonj.github.io/kis-trader/cli.html) · [Claude Skill](https://seokhoonj.github.io/kis-trader/claude-skill.html) · [Codex Skill](https://seokhoonj.github.io/kis-trader/codex-skill.html) |
+| **Reference** | [Realtime (WebSocket)](https://seokhoonj.github.io/kis-trader/realtime.html) · [Limits & gaps](https://seokhoonj.github.io/kis-trader/limits.html) |
+
+The arguments and return value of each method are available through `help(the_method)`.
+
+## 8. License
+
+[MIT](LICENSE)