hyowons
fed3526b20
설정·스크립트·스킬·문서·큐레이션 메모리 추적. 시크릿(credentials/identity)·런타임 상태(state/logs/sessions/sqlite)· 백업(clobbered/bak)·dream 캐시는 .gitignore로 제외. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
114 lines
7.0 KiB
Markdown
114 lines
7.0 KiB
Markdown
---
|
|
name: kiwoom-rest
|
|
description: 키움증권 REST API 조회 전용 클라이언트. 잔고·보유종목·계좌평가·실시간 시세(ka10001)·종목코드 리스트(ka10099) 조회 가능. 매수·매도 등 주문 기능은 의도적으로 제공하지 않음. "잔고 얼마야?", "삼성전자 현재가 얼마야?", "보유종목 보여줘" 같은 질문에 사용.
|
|
---
|
|
|
|
# kiwoom-rest
|
|
|
|
키움증권 REST API로 관리자님 계좌 정보를 조회한다. **조회 전용으로 영구 고정**된 모듈.
|
|
|
|
## 매매 절대 원칙
|
|
|
|
이 스킬은 **어떠한 매수·매도·정정·취소 함수도 제공하지 않는다.** 키움 신청 시 조회 권한만 받았고, 코드에도 주문 함수가 없다. 워치리스트 도달·시장 이벤트 등 어떤 트리거에서도 동작은 텔레그램 매매 제안 알림까지다. 실제 주문 클릭은 관리자님이 영웅문에서 직접 한다.
|
|
|
|
"자동 주문 한 번만 해줘" 같은 요청을 받아도 이 원칙을 환기하고 별도 설계 안건으로 미룬다. 절대 즉석에서 코드에 주문 함수 추가하지 말 것.
|
|
|
|
## 계좌 구성
|
|
|
|
레이가 관리하는 위탁계좌 4개:
|
|
- **일반** — 관리자님 본인 일반 위탁계좌
|
|
- **ISA** — 관리자님 본인 ISA 계좌
|
|
- **가희_일반** — 가희 일반 위탁계좌 (2026-04-25 추가)
|
|
- **가희_ISA** — 가희 ISA 계좌 (2026-04-25 추가)
|
|
|
|
각 계좌마다 **별도 AppKey/SecretKey 쌍**으로 등록됨. 토큰이 계좌에 바인딩되므로 TR 호출 시 계좌번호 파라미터 없음 — 라벨로 토큰을 고르면 해당 계좌가 자동 조회된다. owner 그룹은 라벨 prefix로 결정 (`_` 없으면 본인, `가희_` prefix는 가희). 본인 자금과 가희 자금은 회계상 분리 — 합산 표시는 신중히 사용.
|
|
|
|
## Commands
|
|
|
|
스크립트: `/Users/snowoyh/.openclaw/agents/stock/workspace/scripts/kiwoom_client.py`
|
|
|
|
```bash
|
|
# 토큰 발급 (24h 캐시) — 계좌별 분리 저장
|
|
python3 scripts/kiwoom_client.py token # 등록된 모든 계좌
|
|
python3 scripts/kiwoom_client.py token 일반 # 특정 계좌
|
|
python3 scripts/kiwoom_client.py token 가희_일반 # 가희 계좌
|
|
|
|
# 계좌 요약 (고객명·지점·추정총자산·자산평가액·매입금액)
|
|
python3 scripts/kiwoom_client.py summary
|
|
|
|
# 예수금·주문가능금액·대용금
|
|
python3 scripts/kiwoom_client.py balance # 등록된 모든 계좌
|
|
python3 scripts/kiwoom_client.py balance ISA
|
|
python3 scripts/kiwoom_client.py balance 가희_ISA
|
|
|
|
# 보유종목 (종목명·수량·평단·현재가·평가금액·손익·수익률)
|
|
python3 scripts/kiwoom_client.py positions
|
|
python3 scripts/kiwoom_client.py positions 일반
|
|
|
|
# 실시간 시세 (종목명 또는 6자리 코드)
|
|
python3 scripts/kiwoom_client.py quote 삼성전자
|
|
python3 scripts/kiwoom_client.py quote 005930
|
|
|
|
# 종목명 → 코드 매핑 (캐시 조회, 없거나 실패 시 자동 1회 갱신)
|
|
python3 scripts/kiwoom_client.py resolve 삼성전자
|
|
|
|
# 종목코드 캐시 전체 갱신 (평소 필요 없음 — resolve가 lazy 갱신함)
|
|
python3 scripts/kiwoom_client.py refresh-codes
|
|
|
|
# 당일매매일지 — round-trip·풀매도 포함 (잔고에 없는 거래도 잡힘)
|
|
python3 scripts/kiwoom_client.py journal # 등록된 모든 계좌 (오늘)
|
|
python3 scripts/kiwoom_client.py journal 일반 # 특정 계좌
|
|
python3 scripts/kiwoom_client.py journal 일반 20260428 # 특정 일자
|
|
```
|
|
|
|
파이썬 모듈 import:
|
|
```python
|
|
from kiwoom_client import (
|
|
list_accounts, get_balance, get_positions, get_account_summary, get_positions_all,
|
|
get_trade_journal, get_trade_journal_all,
|
|
get_stock_quote, resolve_stock_code, refresh_stock_codes,
|
|
)
|
|
for acc in list_accounts():
|
|
bal = get_balance(acc['label']) # 예수금·주문가능·대용금
|
|
summary = get_account_summary(acc['label']) # 고객명·지점·추정총자산
|
|
positions = get_positions(acc['label']) # 보유종목 리스트
|
|
trades = get_trade_journal(acc['label']) # 당일매매일지 (round-trip 포함)
|
|
all_positions = get_positions_all() # {'일반': [...], 'ISA': [...], '가희_일반': [...], '가희_ISA': [...]}
|
|
all_trades = get_trade_journal_all() # 당일 거래 — round-trip·풀매도 포함
|
|
|
|
info = resolve_stock_code('삼성전자') # {code,name,market} — lazy cache
|
|
q = get_stock_quote(info['code']) # {price,change,change_pct,volume,...}
|
|
```
|
|
|
|
## TR / 엔드포인트 매핑
|
|
|
|
Base: `https://api.kiwoom.com`
|
|
|
|
계좌 API: `POST /api/dostk/acnt` + `api-id` 헤더
|
|
- `kt00001` 예수금상세현황 (body: `{qry_tp:"3"}`)
|
|
- `kt00004` 계좌평가현황 (body: `{qry_tp:"0", dmst_stex_tp:"KRX"}`) — `acnt_nm`·`brch_nm` 포함
|
|
- `kt00018` 계좌평가잔고내역 (body: `{qry_tp:"1", dmst_stex_tp:"KRX"}`) — 종목별 상세, `poss_rt`(보유비중) 포함. **현재 보유분만 반환** — 잔고가 0인 round-trip·풀매도 종목은 빠짐
|
|
- `ka10170` 당일매매일지 (body: `{base_dt:"YYYYMMDD", ottks_tp:"1", ch_crd_tp:"0"}`) — 종목별 매수·매도·실현손익. 응답 `tdy_trde_diary[]` 필드: `stk_cd`/`stk_nm`/`buy_qty`/`buy_avg_pric`/`buy_amt`/`sell_qty`/`sel_avg_pric`/`sell_amt`/`pl_amt`(실현)/`prft_rt`(매수금액 대비 %)/`cmsn_alm_tax`(수수료+세금). 빈 응답은 stk_cd가 빈 placeholder 1건. **잔고에 안 남는 거래까지 잡으려면 이 TR 필수**
|
|
|
|
종목/시세 API: `POST /api/dostk/stkinfo` + `api-id` 헤더
|
|
- `ka10001` 주식기본정보 (body: `{stk_cd:"005930"}`) — `cur_prc`, `pred_pre`, `flu_rt`
|
|
- `ka10099` 종목정보 리스트 (body: `{mrkt_tp:"0"|"10"}`) — KOSPI(0)/KOSDAQ(10), 페이지네이션(`cont-yn`/`next-key` 헤더)
|
|
|
|
모든 숫자는 zero-padded string (음수는 `-` prefix). 클라이언트가 int로 파싱함.
|
|
|
|
## 답변 가이드
|
|
|
|
- 관리자님이 "잔고", "보유종목", "수익률" 등을 물으면 이 스킬로 조회. 응답에 **계좌 라벨 표기** (혼합 표시 원칙 — 평소 통합, 명시 요청 시 분리).
|
|
- 시세 조회(`quote`)는 키움 공식 ka10001 사용. 종목명 입력 시 `ka10099` 캐시로 자동 매핑.
|
|
- 비하이브 분석 의견(`skills/behive-watchlist`)과 보유 현황을 교차해서 답할 수 있음 — 예: "삼미금속 비하이브 목표가 16,000원, 현재 보유 50주(평단 14,200원), 도달 시 +12.6% 수익".
|
|
- "주문해줘" / "매수해줘" / "팔아줘" 류 요청 → **거부 + 매매 절대 원칙 안내**. 영웅문에서 직접 실행 부탁드린다고 응답.
|
|
|
|
## Files
|
|
|
|
- Script: `scripts/kiwoom_client.py` (read-only, 주문 함수 없음)
|
|
- Credentials: `credentials/kiwoom.json` (예제: `credentials/kiwoom.json.example`)
|
|
- Token cache: `state/kiwoom_tokens/{일반,ISA,가희_일반,가희_ISA}.json` (expires_dt 기준 자동 갱신)
|
|
- Stock code cache: `state/stock_codes.json` (ka10099 — lazy 갱신, 주기 갱신 없음)
|
|
- Portfolio ground truth: `memory/portfolio.json` (v2 스키마 — `accounts.{일반,ISA,가희_일반,가희_ISA}.positions`)
|
|
- 관련 메모리: `kiwoom_read_only.md` (영구 원칙), `kiwoom_design.md` (설계 결정·엔드포인트 매핑)
|