Metadata-Version: 2.4
Name: stockclaw-kit
Version: 3.5.7
Summary: Korean stock market data & trading toolkit — CLI direct call
Author-email: OpenClaw <dev@openclaw.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,kis,kiwoom,korea,naver,pykrx,stock,stockclaw,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: pykrx>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: telethon>=1.36.0
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: all
Requires-Dist: websockets>=12.0; extra == 'all'
Provides-Extra: db
Provides-Extra: kis
Provides-Extra: kiwoom
Requires-Dist: websockets>=12.0; extra == 'kiwoom'
Description-Content-Type: text/markdown

# OpenClaw Stock Kit — 한국 주식 데이터 & 매매 도구

> API 키만 설정하면, AI에게 주식 질문을 자연어로 바로 물어볼 수 있습니다.
> PyKRX 무료 주가 + 키움 185개 API + 한국투자 166개 API + 뉴스/공시를 한 번에.

---

## 이게 뭔가요?

AI(Claude, Cursor 등)는 보통 주식 데이터를 직접 가져올 수 없어요.
이 프로그램을 설치하면 AI가 **"삼성전자 오늘 주가 알려줘"** 같은 요청을 직접 처리할 수 있게 됩니다.

3가지 방식으로 사용 가능합니다:

| 방식 | 설명 | 용도 |
|------|------|------|
| **CLI 직접 호출** | `stockclaw-kit run <도구> '<JSON>'` | OpenClaw, 스크립트, 자동화 |
| **Setup Wizard** | `http://localhost:8200` 브라우저 설정 | API 키 설정, 상태 확인 |

---

## 빠른 시작 (pip 설치)

### 필요한 것

| 항목 | 버전 | 확인 방법 |
|------|------|---------|
| Python | 3.11 이상 | `python --version` |

```bash
pip install stockclaw-kit
```

설치 후 서버를 실행하면 브라우저에서 Setup Wizard가 열립니다:

```bash
stockclaw-kit                    # 서버 시작 → http://localhost:8200
```

Setup Wizard에서 사용할 기능을 선택하고 API 키를 입력하면 설정 완료!

---

### CLI 직접 호출

```bash
# 도구 목록 확인
stockclaw-kit run list

# 상태 확인
stockclaw-kit run gateway_status

# 종목 검색 (무료, 키 불필요)
stockclaw-kit run datakit_call '{"function":"search_stock","params_json":"{\"keyword\":\"삼성전자\"}"}'

# 과거 주가 조회 (무료)
stockclaw-kit run datakit_call '{"function":"get_price","params_json":"{\"ticker\":\"005930\",\"start\":\"20260101\",\"end\":\"20260219\"}"}'

# 뉴스 검색
stockclaw-kit run news_search_stock '{"stock_name":"삼성전자","days":7}'
```

> `run` 모드는 도구를 직접 실행하는 방식입니다. 스크립트/파이프라인에 적합합니다.
> stdout에 순수 JSON만 출력되어 파이프라인/스크립트에 적합합니다.

---

### OpenClaw 스킬로 설치하기

```bash
clawhub install https://github.com/readinginvestor/stock-kit
```

OpenClaw 텔레그램 봇에서 "삼성전자 주가 알려줘" 같은 자연어 질문을 바로 처리합니다.

---

## 무료로 제공하는 도구 (총 26개)

### 모듈별 구성

| 모듈 | 도구 이름 | 기능 | API 수 |
|------|---------|------|-------|
| **Stock Data Kit** | `datakit_call` | 주가, 시총, 수급, 공시, 거시지표, 환율 조회 | 13개 함수 |
| **Kiwoom** | `kiwoom_call_api` | 키움증권 실시간 시세 + 주문 | 185개 API |
| **KIS** | `kis_domestic_stock` 외 | 한국투자증권 국내/해외 시세 + 주문 | 166개 API |
| **News** | `news_search` 외 | 네이버 뉴스 + 텔레그램 채널 메시지 | 6개 도구 |
| **멤버십 데이터** | `membership_call` | AI 시장 요약, 종목 뉴스 매칭, 테마 이벤트, 주도주시황, 장전뉴스, 뉴욕증시, 오후장 특징종목 | 8개 API |
| **Gateway** | `gateway_status` | 전체 상태 확인 + 도구 선택 가이드 | 1개 도구 |

---

### Stock Data Kit — 주요 함수 13개

`datakit_call(function, params_json)` 형태로 호출합니다.

| 함수명 | 기능 | API 키 필요 여부 |
|--------|------|--------------|
| `get_price` | 현재가, 등락률, 거래량 | 불필요 (PyKRX) |
| `get_ohlcv` | 일/주/월 OHLCV 차트 데이터 | 불필요 |
| `get_market_cap` | 시가총액, 상장주식수 | 불필요 |
| `get_supply` | 외국인/기관 수급 | 불필요 |
| `get_index` | 코스피/코스닥 지수 | 불필요 |
| `search_stock` | 종목명 → 종목코드 검색 | 불필요 |
| `dart_disclosures` | DART 공시 목록 | DART_API_KEY |
| `dart_company` | 기업 기본 정보 | DART_API_KEY |
| `ecos_indicator` | 한국은행 거시지표 (기준금리 등) | ECOS_API_KEY |
| `exchange_rate` | 환율 (USD, EUR, JPY 등) | EXIM_API_KEY |
| `governance_majority` | 최대주주 현황 | DART_API_KEY |
| `governance_bulk_holding` | 5% 이상 대량보유 | DART_API_KEY |
| `governance_executives` | 임원 현황 | DART_API_KEY |

**사용 예시:**
```
datakit_call("get_price", '{"ticker":"005930"}')              → 삼성전자 현재가
datakit_call("get_ohlcv", '{"ticker":"005930","days":30}')    → 30일 차트
datakit_call("dart_disclosures", '{"days":3}')                → 최근 3일 공시
datakit_call("exchange_rate", '{"currencies":["USD","EUR"]}') → 달러/유로 환율
```

---

### Kiwoom — 키움증권 REST API 185개

`kiwoom_call_api(tr_code, params_json)` 형태로 호출합니다.

키움증권 계좌와 API 키가 있어야 사용 가능합니다.

| 카테고리 | 코드 예시 | 기능 |
|---------|---------|------|
| 주식 시세 | `ka10001` | 현재가 조회 |
| 호가/체결 | `ka10004` | 호가 조회 |
| 순위 | `ka10019` | 등락률 순위 |
| 매수 주문 | `kt10000` | 주식 매수 |
| 매도 주문 | `kt10001` | 주식 매도 |
| 정정/취소 | `kt10002` | 주문 정정 |
| 조건검색 | `kiwoom_condition_search` | 실시간 조건검색 |

> **주의:** 주문 API(kt10000, kt10001 등)는 **사용자 본인의 키움 계좌와 API 키로만 동작**합니다.
> 이 프로그램은 주문을 자동으로 실행하지 않습니다. 사용자가 직접 요청해야 합니다.

---

### KIS — 한국투자증권 166개 API

카테고리별로 도구가 나뉩니다:

| 도구 이름 | 카테고리 | API 수 |
|---------|---------|-------|
| `kis_domestic_stock` | 국내주식 시세/매매 | 74개 |
| `kis_overseas_stock` | 해외주식 시세/매매 | 34개 |
| `kis_domestic_bond` | 국내채권 | 14개 |
| `kis_domestic_futureoption` | 국내선물옵션 | 20개 |
| `kis_overseas_futureoption` | 해외선물옵션 | 19개 |
| `kis_etfetn` | ETF/ETN | 2개 |
| `kis_auth` | 인증 관리 | 2개 |

---

### 멤버십 데이터 — 데이터 피드 API 8개

`membership_call(api_id, params_json)` 형태로 호출합니다.

readinginvestor.com 멤버십과 API 키가 있어야 사용 가능합니다.

| API ID | 기능 | 필수 파라미터 |
|--------|------|-------------|
| `ka-002` | 종목 뉴스 매칭 | stock_code |
| `ka-004` | 테마별 이벤트 | — |
| `ka-005` | 종목별 뉴스 통합 | stock_code |
| `ka-006` | AI 일일 요약 | — |
| `ka-007` | 뉴욕증시 | — |
| `ka-008` | 주도주시황 | — |
| `ka-009` | 장전뉴스 | — |
| `ka-010` | 오후장 특징종목 | — |

> 모든 API의 응답은 AI가 분석한 결과입니다. 원본 뉴스가 필요하면 `news_search_stock`을 사용하세요.

---

## API 키 발급 방법

### PyKRX (주가/시총/수급) — 키 없이 바로 사용 가능

별도 가입 없이 즉시 사용 가능합니다.

### DART 공시 API 키

1. [opendart.fss.or.kr](https://opendart.fss.or.kr) 접속
2. 회원가입 → 로그인
3. 마이페이지 → API 신청 → 키 발급 (무료)
4. 환경변수에 설정: `DART_API_KEY=발급받은키`

### ECOS 한국은행 경제지표 API 키

1. [ecos.bok.or.kr](https://ecos.bok.or.kr) 접속
2. 회원가입 → 오픈API → 인증키 신청 (무료)
3. 환경변수에 설정: `ECOS_API_KEY=발급받은키`

### EXIM 수출입은행 환율 API 키

1. [www.koreaexim.go.kr](https://www.koreaexim.go.kr) 접속
2. 오픈API 신청 → 키 발급 (무료)
3. 환경변수에 설정: `EXIM_API_KEY=발급받은키`

### 키움증권 REST API

1. [www.kiwoom.com](https://www.kiwoom.com) → OpenAPI 신청
2. 계좌 개설 후 API 사용 신청
3. 발급된 `app_key`, `app_secret` 환경변수 설정

### 한국투자증권(KIS) Open API

1. [www.truefriend.com](https://www.truefriend.com) → KIS Developers
2. 계좌 개설 후 API 키 발급
3. `KIS_APP_KEY`, `KIS_APP_SECRET` 환경변수 설정

### 멤버십 데이터 피드 API 키

1. [readinginvestor.com](https://readinginvestor.com) 접속
2. 회원가입 → 멤버십 구독
3. 프로필 → 내정보 → API 키 탭 → "API 키 발급" 클릭
4. 환경변수에 설정: `MEMBERSHIP_API_KEY=tt_live_발급받은키`

---

## 환경변수 설정 방법

API 키를 입력하는 방법은 두 가지입니다.

### 방법 1 — 브라우저 설정 페이지 (pip 설치 시)

`pip install stockclaw-kit`로 직접 설치한 경우, 서버를 실행하면 브라우저 설정 페이지가 열립니다:

```bash
pip install stockclaw-kit
stockclaw-kit                # http://localhost:8200 자동 오픈
```

브라우저에서 각 API 키를 입력하고 저장하면 `~/.stockclaw-kit/.env`에 자동 저장됩니다.

> **직접 설치 시** 브라우저 설정 페이지를 사용할 수 있습니다.
> 이 경우 아래 방법 2를 사용하세요.

### 방법 2 — 파일 직접 수정

`~/.stockclaw-kit/.env` 파일을 직접 편집합니다 (없으면 새로 만드세요):

```bash
DART_API_KEY=your_dart_key
ECOS_API_KEY=your_ecos_key
EXIM_API_KEY=your_exim_key
KIS_APP_KEY=your_kis_key
KIS_APP_SECRET=your_kis_secret
KIWOOM_APP_KEY=your_kiwoom_key
KIWOOM_APP_SECRET=your_kiwoom_secret
```

또는 터미널에서 임시 설정 (재시작하면 초기화됨):

```bash
export DART_API_KEY=your_dart_key
```

---

## 응답 형식

모든 도구는 동일한 JSON 형식으로 응답합니다:

```json
{
  "ok": true,
  "source": "datakit",
  "asof": "2026-02-18T09:30:00+09:00",
  "data": { ... },
  "meta": null,
  "error": null
}
```

| 필드 | 의미 |
|------|------|
| `ok` | 성공 여부 (true/false) |
| `source` | 데이터 출처 (datakit, kiwoom, kis 등) |
| `asof` | 응답 시각 (한국시간 KST) |
| `data` | 실제 데이터 |
| `error` | 오류 발생 시 코드와 메시지 |

에러 예시:
```json
{
  "ok": false,
  "source": "datakit",
  "data": null,
  "error": { "code": "API_KEY_MISSING", "message": "DART_API_KEY가 설정되지 않았습니다" }
}
```

전체 에러 코드 목록은 [STANDARD.md](STANDARD.md) 참고.

---

## 프리미엄 기능 (라이선스 키 필요)

무료 도구와 별개로, 라이선스 키가 있으면 추가 기능을 사용할 수 있습니다.
**책전주식**이 제공하는 당일 단타매매 준비 실시간 정보, 장 마감 주도주 정리, 흐름 패턴 차트 분석 자료 등이 포함됩니다.

| 기능 | 설명 |
|------|------|
| 오전 단타장 준비 브리핑 + 오후장 시장 정리 분석 | AI가 생성한 장전·장후 시장 요약 |
| TOP30/메모/관심종목 JHTS 자동반영 엑셀 | 일별 주도주 순위 + 분석 엑셀 다운로드 |
| 백테스트 | 종목 데이터 분석을 통한 종가매매 등 전략 시뮬레이션 |
| 매매기법 발굴 AI활용 강의 | AI를 활용한 데이터 수집·백테스팅·매매기법 수립 단계별 강의 |

```bash
# 환경변수로 라이선스 키 설정
export OPENCLAW_LICENSE_KEY=OCKP-XXXXXX-XXXXXX-XXXXXX
```

라이선스 키가 없어도 무료 도구(PyKRX, 키움, KIS)는 정상 작동합니다.

구독: https://readinginvestor.com/openclaw

---

## 아키텍처 — 하나의 게이트웨이로 전부 연결

각 모듈(PyKRX, 키움, KIS, 뉴스, 프리미엄)은 각자 별도의 파일로 구성되어 있지만,
게이트웨이 구조로 모든 모듈이 통합되어 있습니다. CLI, OpenClaw 스킬 등 다양한 방식으로 모든 기능을 사용할 수 있습니다.

```
Claude Code / Cursor
        │
        │ (stdio 또는 SSE — 단일 연결)
        ▼
┌─────────────────────────────────────────┐
│      OpenClaw Stock Kit (Gateway)      │
│                                         │
│  ├─ datakit_call      ← PyKRX, DART,    │
│  │                       ECOS, 환율      │
│  ├─ kiwoom_call_api   ← 키움 REST 185개  │
│  ├─ kis_domestic_stock ← 한투 국내166개  │
│  ├─ news_search       ← 네이버/텔레그램  │
│  ├─ premium_call      ← 프리미엄 기능   │
│  ├─ membership_call  ← 데이터 피드 8개  │
│  └─ gateway_status    ← 전체 상태 확인  │
└─────────────────────────────────────────┘
```

### 처음 시작할 때는 `gateway_status`부터

어떤 도구가 활성화됐는지, 어떤 기능을 쓸 수 있는지 한눈에 확인할 수 있습니다:

```
gateway_status()
→ 활성 모듈 수 / 전체 모듈 수
→ 시나리오별 권장 도구 가이드
→ API 키 설정 여부
```

모듈별로 키가 없거나 연결에 실패해도 **다른 모듈에는 영향 없이** 정상 작동합니다.
예: 키움 계좌가 없어도 PyKRX 주가 조회는 바로 사용 가능.

---

## 버전 고정 (CI/프로덕션 환경)

버전이 바뀌어도 동일한 버전을 유지하고 싶을 때:

```bash
pip install stockclaw-kit==2.0.0   # pip: 정확히 이 버전
```

---

## 데이터 출처

| 출처 | 제공 데이터 | 비고 |
|------|-----------|------|
| [PyKRX](https://github.com/sharebook-kr/pykrx) | 주가, 시총, 수급, 지수 | 무료, 키 불필요 |
| [OpenDART](https://opendart.fss.or.kr) | 기업 공시 | 무료 API 키 필요 |
| [ECOS](https://ecos.bok.or.kr) | 한국은행 거시지표 | 무료 API 키 필요 |
| [EXIM Bank](https://www.koreaexim.go.kr) | 환율 | 무료 API 키 필요 |
| [키움증권](https://www.kiwoom.com) | 실시간 시세 + 주문 (185개) | 계좌 필요 |
| [한국투자증권](https://www.truefriend.com) | 국내/해외 시세 + 주문 (166개) | 계좌 필요 |

---

## 보안

- **API 키 저장 위치**: `~/.stockclaw-kit/.env` (폴더 권한 700, 파일 권한 600)
- **라이선스 검증**: 서버 검증 → 24시간 grace → fail-open (로컬 HMAC 허용)
- **네트워크**: 외부 API 호출은 전부 HTTPS
- **사용 데이터 수집 없음**: 사용 기록, 텔레메트리 일절 없음

---

## ABI 계약 (도구 이름 영구 보장)

`datakit_call`, `kiwoom_call_api`, `kis_domestic_stock` 등 **도구 이름은 절대 바뀌지 않습니다.**
한 번 연동한 코드가 버전 업그레이드 후에도 그대로 작동하도록 보장합니다.
변경이 불가피할 경우 최소 3개 마이너 버전 동안 deprecated 경고를 먼저 제공합니다.

자세한 내용: [STANDARD.md](STANDARD.md)

---

## 라이선스

MIT — 상업적 이용 포함 자유롭게 사용 가능합니다.
