---
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` (설계 결정·엔드포인트 매핑)
