krx-openapi 0.1.0__tar.gz

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

@@ -0,0 +1,20 @@
+{
+  "name": "krx-openapi",
+  "interface": {
+    "displayName": "krx"
+  },
+  "plugins": [
+    {
+      "name": "krx",
+      "source": {
+        "source": "local",
+        "path": "./plugins/krx"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "name": "krx-openapi",
+  "owner": {
+    "name": "seokhoonj"
+  },
+  "description": "Read the Korea Exchange (KRX) Open API",
+  "plugins": [
+    {
+      "name": "krx",
+      "displayName": "krx",
+      "source": "./plugins/krx",
+      "description": "Read the Korea Exchange (KRX) Open API",
+      "author": {
+        "name": "seokhoonj"
+      },
+      "homepage": "https://github.com/seokhoonj/krx-openapi",
+      "category": "Productivity",
+      "keywords": [
+        "krx",
+        "korea exchange",
+        "korea",
+        "market data",
+        "stock"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,22 @@
+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:
+    uses: ./.github/workflows/reusable-check.yml

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

@@ -0,0 +1,61 @@
+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 krx-openapi / 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
+      - 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

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

@@ -0,0 +1,83 @@
+name: reusable check
+
+# The full check -- tests, lint, types, and the zero-dependency assertion -- factored
+# into one reusable job so both `check.yml` (on push / PR) and any release gate run
+# the *identical* thing.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # The floor and the current release. requires-python is >=3.11, so 3.11 is
+        # the version that claim has to hold on; the upper end tracks current CPython.
+        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
+        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: Types
+        run: .venv/bin/mypy
+
+      - name: Confirm the package still has no runtime dependencies
+        # The zero-dependency claim is in the README and pyproject; a claim nothing
+        # checks quietly stops being true. Installed into a bare environment, the
+        # package must import with nothing else present.
+        run: |
+          uv venv /tmp/bare --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/bare/bin/python .
+          /tmp/bare/bin/python -c "
+          import importlib.metadata as md
+          requires = md.requires('krx-openapi') or []
+          runtime = [r for r in requires if 'extra ==' not in r]
+          assert not runtime, f'runtime dependencies appeared: {runtime}'
+          import krx_openapi
+          print('krx_openapi', krx_openapi.__version__, 'imports with no third-party packages')
+          "
+          # The console script runs, and its top-level --version prints (not shoved
+          # into a required subcommand).
+          /tmp/bare/bin/krx --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/krx_openapi/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 krx_openapi import KRX
+
+          # market is Literal["KOSPI","KOSDAQ","KONEX"]; an int is none of them, so a
+          # checker that can see the shipped hints must reject it. If py.typed is
+          # missing from the wheel, mypy skips krx_openapi and emits no such error.
+          KRX(api_key="k").stock.daily("20200414", market=123)
+          PY
+          /tmp/typed/bin/mypy /tmp/user_code.py > /tmp/mypy_out 2>&1 || true
+          cat /tmp/mypy_out
+          grep -q 'incompatible type' /tmp/mypy_out

krx_openapi-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# uv
+uv.lock
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local scratch (never tracked)
+dev/
+refs/
+
+# AI coding agents
+CLAUDE.md
+.claude/
+AGENTS.md
+AGENT.md
+.codex/
+GEMINI.md
+.gemini/

krx_openapi-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.

krx_openapi-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: krx-openapi
+Version: 0.1.0
+Summary: Read the Korea Exchange (KRX) Open API: indices, stocks, ETP, bonds, derivatives, commodities, ESG.
+Project-URL: Homepage, https://github.com/seokhoonj/krx-openapi
+Project-URL: Repository, https://github.com/seokhoonj/krx-openapi
+Project-URL: Issues, https://github.com/seokhoonj/krx-openapi/issues
+Author-email: Seokhoon Joo <seokhoonj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: finance,korea,korea exchange,krx,market data,한국거래소
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# krx-openapi
+
+[![check](https://github.com/seokhoonj/krx-openapi/actions/workflows/check.yml/badge.svg)](https://github.com/seokhoonj/krx-openapi/actions/workflows/check.yml)
+[![PyPI](https://img.shields.io/pypi/v/krx-openapi)](https://pypi.org/project/krx-openapi/)
+[![Python](https://img.shields.io/pypi/pyversions/krx-openapi)](https://pypi.org/project/krx-openapi/)
+[![License](https://img.shields.io/pypi/l/krx-openapi)](https://github.com/seokhoonj/krx-openapi/blob/main/LICENSE)
+
+[English](https://github.com/seokhoonj/krx-openapi/blob/main/README.en.md) | **한국어**
+
+한국거래소 **KRX Open API**의 일별 시장 데이터를 읽어옵니다.
+
+지수(KRX·KOSPI·KOSDAQ·채권·파생), 주식 일별매매정보와 종목기본정보, ETF·ETN·ELW,
+채권(국채·일반·소액), 선물·옵션, 석유·금·배출권, 그리고 ESG까지 — **공식 API가
+제공하는 7개 서비스, 31개 항목**을 다룹니다.
+
+## 1. 설치
+
+```bash
+pip install krx-openapi
+```
+
+무료 인증키는 <https://openapi.krx.co.kr> 에서 발급받습니다. **인증키만으로는 호출이
+안 되고**, '서비스 이용' 메뉴에서 사용할 개별 API를 신청하고 승인을 받아야 합니다.
+
+**config 파일 (모든 OS 공통, 권장)** — `~/.config/krx-openapi/credentials.json`
+(`~`는 홈 폴더 — Linux `/home/이름`, macOS `/Users/이름`, Windows `C:\Users\이름`):
+
+```json
+{ "KRX_API_KEY": "발급받은-키" }
+```
+
+**환경변수** — macOS·Linux: `export KRX_API_KEY=...` / Windows PowerShell:
+`setx KRX_API_KEY "..."`.
+
+## 2. 빠른 시작
+
+```python
+from krx_openapi import KRX
+
+krx = KRX(api_key="your-key")                   # 또는 KRX() — 저장해둔 키(env/config)를 자동으로 찾음
+
+rows = krx.index.kospi("20200414")              # KOSPI 시리즈 지수, 하루치
+
+krx.stock.daily("20200414", market="KOSPI")     # KOSPI 전종목 일별매매정보
+krx.etp.etf("20200414")                         # ETF 일별매매정보
+```
+
+날짜(`date`)는 `YYYYMMDD` 거래일입니다. 반환은 `dict`의 목록(`list`)이라, 표(DataFrame)로
+한 줄에 바뀝니다 (pandas는 필수가 아닙니다).
+
+```python
+# pandas
+import pandas as pd
+pd.DataFrame(rows)
+
+# polars
+import polars as pl
+pl.DataFrame(rows)
+```
+
+## 3. API
+
+| 접근자 | 서비스 |
+|---|---|
+| `krx.index` | KRX·KOSPI·KOSDAQ 시리즈, 채권지수, 파생상품지수 일별시세 |
+| `krx.stock` | KOSPI/KOSDAQ/KONEX 일별매매·종목기본정보, 신주인수권증권·증서 |
+| `krx.etp` | ETF·ETN·ELW 일별매매정보 |
+| `krx.bond` | 국채전문·일반·소액채권 일별매매정보 |
+| `krx.derivatives` | 선물·옵션·주식선물·주식옵션 일별매매정보 |
+| `krx.commodity` | 석유·금·배출권 일별매매정보 |
+| `krx.esg` | 사회책임투자채권·ESG 지수·ESG 증권상품 |
+
+전체 메서드 (모든 인자 `date` = `YYYYMMDD` 거래일):
+
+```text
+KRX()
+├─ index                                       # 지수
+│   ├─ .krx(date)                              KRX 시리즈 일별시세
+│   ├─ .kospi(date)                            KOSPI 시리즈 일별시세
+│   ├─ .kosdaq(date)                           KOSDAQ 시리즈 일별시세
+│   ├─ .bond(date)                             채권지수 시세
+│   └─ .derivatives(date)                      파생상품지수 시세
+├─ stock                                       # 주식
+│   ├─ .info(date, market="KOSPI")             종목기본정보 (KOSPI/KOSDAQ/KONEX)
+│   ├─ .daily(date, market="KOSPI")            일별매매정보 (KOSPI/KOSDAQ/KONEX)
+│   ├─ .warrant(date)                          신주인수권증권
+│   └─ .right(date)                            신주인수권증서
+├─ etp                                         # 증권상품
+│   ├─ .etf(date)                              ETF
+│   ├─ .etn(date)                              ETN
+│   └─ .elw(date)                              ELW
+├─ bond                                        # 채권
+│   ├─ .treasury(date)                         국채전문유통시장
+│   ├─ .general(date)                          일반채권시장
+│   └─ .small_lot(date)                        소액채권시장
+├─ derivatives                                 # 파생상품
+│   ├─ .futures(date)                          선물 (주식선물外)
+│   ├─ .options(date)                          옵션 (주식옵션外)
+│   ├─ .stock_futures(date, market="KOSPI")    주식선물 (KOSPI/KOSDAQ)
+│   └─ .stock_options(date, market="KOSPI")    주식옵션 (KOSPI/KOSDAQ)
+├─ commodity                                   # 일반상품
+│   ├─ .oil(date)                              석유시장
+│   ├─ .gold(date)                             금시장
+│   └─ .emissions(date)                        배출권시장
+└─ esg                                         # ESG
+    ├─ .sri_bond(date)                         사회책임투자채권
+    ├─ .index(date)                            ESG 지수
+    └─ .etp(date)                              ESG 증권상품
+```
+
+어떤 서비스에 어떤 필드가 오는지는 네트워크 없이 오프라인으로 확인할 수 있습니다.
+
+```python
+from krx_openapi import catalog
+
+catalog.groups()                  # ['index', 'stock', ...]
+catalog.methods("bond")           # ['treasury', 'general', 'small_lot']
+catalog.fields("index", "kospi")  # 이 서비스가 돌려주는 필드명 (컬럼)
+```
+
+## 4. 커맨드라인
+
+명령줄은 세 명령 `list` · `fields` · `fetch`를 씁니다. `list`·`fields`는 오프라인(키
+불필요)으로 뭐가 있고 어떤 컬럼이 오는지 훑고, `fetch`는 하루치 데이터를 가져옵니다 —
+`krx fetch <그룹> <메서드> <날짜>` (예: `krx fetch index kospi 20200414` =
+`krx.index.kospi("20200414")`). 명령은 `krx` 또는 `python -m krx_openapi`로 실행하고,
+어디에 `--json`을 붙이면 JSON으로 나옵니다.
+
+```bash
+# 무슨 서비스가 있나 / 어떤 컬럼이 오나 (오프라인, 키 불필요)
+krx list                      # 전체 그룹·메서드
+krx list stock                # 한 그룹만
+krx fields index kospi        # 이 서비스가 돌려주는 컬럼
+
+# 데이터 조회 (KRX_API_KEY 필요)
+krx fetch index kospi 20200414
+krx fetch stock daily 20200414 --market KOSDAQ
+krx fetch bond treasury 20200414
+```
+
+## 5. AI 코딩 에이전트에서 사용
+
+- 이 저장소는 Claude Code·Codex용 플러그인 마켓플레이스도 겸합니다.
+- `list`·`fields`·`fetch` 스킬을 제공하며, 각각 같은 이름의 `krx` 명령을 호출합니다
+  (`krx list`, `krx fields <그룹> <이름>`, `krx fetch <그룹> <이름> <날짜>`).
+- 먼저 위에서 패키지를 설치하세요 (`list`·`fields`는 키 없이, `fetch`는 API 키가 필요합니다).
+
+### 5.1 Claude Code
+
+```
+/plugin marketplace add seokhoonj/krx-openapi
+/plugin install krx@krx-openapi
+```
+
+설치 후 평범하게 물어보거나("코스피 전종목 시세 가져와", "무슨 KRX 서비스 있어"), 스킬을
+직접 부르세요 — `/krx:list`, `/krx:fields index kospi`, `/krx:fetch index kospi 20200414`.
+
+### 5.2 Codex
+
+```
+codex plugin marketplace add seokhoonj/krx-openapi
+codex plugin add krx@krx-openapi
+```
+
+### 5.3 플러그인 없이 (symlink)
+
+플러그인으로 설치하지 않고 쓰려면, 스킬을 각 에이전트의 스킬 디렉터리에 symlink합니다.
+
+```sh
+for s in list fields fetch; do
+  ln -s "$PWD/plugins/krx/skills/$s" ~/.claude/skills/$s   # Claude Code → /$s
+  ln -s "$PWD/plugins/krx/skills/$s" ~/.codex/skills/$s    # Codex → $krx:$s
+done
+```
+
+Claude Code는 바로 인식하고, Codex는 재시작해야 로딩됩니다.
+
+## 6. 주의사항
+
+- **일별 데이터만.** 당일·실시간·장중 데이터는 없습니다. 전일 데이터가 **다음 영업일
+  오전 8시**에 갱신됩니다. 주말·공휴일, 갱신 전 조회는 빈 결과입니다.
+- **호출 한도**: 인증키당 **하루 10,000회**(IP 아님, 자정 리셋). 초과 시
+  `KRXRateLimitError`(HTTP 429). 과도한 호출은 IP 차단 사유가 됩니다.
+- **단순주가(원주가)만** 제공합니다. 수정주가는 없습니다.
+- **API 미제공 데이터**: 투자자별 거래실적, 외국인 보유량, 공매도, PER/PBR,
+  ETF 구성종목(PDF), 지정내역(투자경고·거래정지·관리종목) 등은 제공되지 않습니다.
+- **이용약관**: 비상업적 목적(개인 연구·투자)만 허용됩니다. 가공하여 표출할 때는 **출처
+  "한국거래소 통계정보"**를 표기하고, 원천 데이터를 제3자에게 재배포할 수 없습니다.
+  자세한 내용은 KRX Open API 이용약관을 확인하세요.
+
+## 7. 에러
+
+모든 에러는 `KRXError`를 상속합니다.
+
+| 예외 | 언제 |
+|---|---|
+| `KRXConfigError` | 인증키를 찾을 수 없음 (요청 전) |
+| `KRXAuthError` | 키 거부 또는 **미신청 서비스** (respCode 401) |
+| `KRXRateLimitError` | 일일 호출 한도 초과 (HTTP 429) |
+| `KRXResponseError` | 그 밖의 벤더 에러 (respCode) |
+| `KRXNetworkError` | 전송 실패·비-JSON 응답·기타 HTTP 에러 |
+
+잘못된 `market` 코드는 `ValueError`, 모르는 서비스 이름은 `KeyError`입니다.
+
+## 8. 라이선스
+
+MIT. 이 패키지의 코드에 대한 라이선스이며, KRX 데이터 자체의 이용 조건은 위 KRX
+이용약관을 따릅니다.