# 2026-04-24 — 키움 REST API 실연동 완료일

관리자님과 함께 키움증권 REST API 조회 전용 통합을 완료했다. 클로 세션에서 진행. 레이 워크스페이스 전반이 REST 기반으로 전환됨.

## 확정된 구조 (여기부터 기본값)

**자격증명** — `/Users/snowoyh/.openclaw/credentials/kiwoom.json` (v2 스키마, chmod 600):
- 계좌별 `appkey`/`secretkey` 쌍 분리 (한 쌍으로는 두 계좌 못 씀이 실연동 중 확인됨)
- `accounts.일반`, `accounts.ISA` 라벨 사용. 계좌번호는 토큰 스코프로 자동 식별되므로 `account_no` 필드는 참고용

**클라이언트** — `scripts/kiwoom_client.py`:
- CLI: `token [label] | accounts | summary | balance [label] | positions [label]`
- 함수: `issue_token(label)`, `get_balance(label)`, `get_account_summary(label)`, `get_positions(label)`, `get_positions_all()`, `list_accounts()`
- 토큰 캐시: `state/kiwoom_tokens/{일반,ISA}.json` (expires_dt 기준 자동 갱신)
- **주문 함수 부재** (매매 절대 원칙 — kiwoom_read_only.md)

**TR 매핑**: base `https://api.kiwoom.com`, 공통 경로 `POST /api/dostk/acnt` + `api-id` 헤더
- `kt00001` 예수금 (body `{qry_tp:"3"}`)
- `kt00004` 계좌평가현황 (body `{qry_tp:"0", dmst_stex_tp:"KRX"}`)
- `kt00018` 계좌평가잔고내역 (body `{qry_tp:"1", dmst_stex_tp:"KRX"}`) — 종목별 상세
- 상세 필드명은 `kiwoom_design.md` 참조

**리포트** — `scripts/stock_portfolio_report.py`:
- 키움 REST 기반으로 완전 재작성. 네이버 시세·portfolio.json 의존 제거
- 기본은 두 계좌 합산 통합 뷰. `--by-account` 플래그로 계좌별 분리 뷰
- 당일 매매 발생 종목은 `tdy_buyq`/`tdy_sellq`로 자동 감지하여 ★ 표시
- `run` / `send` 모드 그대로 유지. 평일 20:10 cron으로 `send` 자동 실행

**portfolio.json** — v2 스키마 (B안)로 마이그레이션 완료:
- `accounts.{일반,ISA}.positions` 중첩 구조
- 참고용 스냅샷일 뿐, 리포트 숫자는 항상 REST 실시간 조회에서 계산

## 폐기된 것

- `scripts/portfolio-update.py` — iMessage 키움 체결통보 파서. REST kt00018이 ground truth가 되면서 중복 해소. 휴지통으로 이동
- cron 잡 "20:00 iMessage 키움 체결 파싱" — `cron/jobs.json`에서 완전 삭제 (잡 9개 → 8개)
- `state/portfolio_trades.json`, `state/kiwoom_chat_ids.json`, `state/portfolio_history.json`, `state/portfolio.json`(v1 legacy) — 전부 휴지통
- `scripts/docs/` 폴더 통째로 (구 매뉴얼 4개, iMessage 파서 전제 문서)
- 백업 파일 3개

## 관리자님 계좌 현황 (2026-04-24 기준)

- **일반**: 4종목, 자산평가 63,940,866원, 매입 40,958,330원
- **ISA**: 13종목, 자산평가 51,521,943원, 매입 40,604,786원
- 합산 15종목 (겹침: SK하이닉스·삼성전자 양쪽 보유), 평가손익 +32,067,306원 (+39.32%)
- 주력: 삼성전자 335주(64.95% 비중), SK하이닉스 17주(18.25%)
- 지점: 온라인지점8, 고객명: 방효원

## 업데이트된 문서

- `workspace/TOOLS.md` — 전면 재작성 (REST 기반)
- `workspace/AGENTS.md` — "portfolio.json 먼저 읽어라" → "kiwoom_client로 실시간 조회"
- `workspace/SOUL.md` — "매매 절대 원칙" 그대로 유지 (원래부터 REST 조회 전용으로 명시돼 있었음)
- `workspace/skills/kiwoom-rest/SKILL.md`, `skills/stock-agent/SKILL.md` — 최신화
- `workspace/MEMORY.md` — 신규 생성. 주식 장기 기억 인덱스
- `~/.openclaw/CLAUDE.md` — 스크립트·cron·credentials 설명 전면 갱신

## 교훈

- 키움 OpenAPI 포털은 SPA라 웹크롤링으로는 엔드포인트·필드명 추출 불가. **probe 스크립트**(토큰으로 직접 호출하고 응답 구조 확인)가 가장 빠른 확정 경로
- 키움 응답 숫자는 전부 zero-padded string. 음수는 `-` prefix. 파싱 헬퍼 필수
- 토큰이 계좌에 바인딩돼 있다는 건 문서에 명시 안 돼 있음 — 계좌번호 파라미터 없이 호출했는데 정상 응답 와서 발견
- 기존 iMessage 누적 portfolio.json은 섞여있었음 — REST로 실측해보니 한 계좌엔 4종목, 다른 계좌엔 13종목이 분리돼 있었다. 가계성 데이터는 ground truth 확보되면 즉시 덮어쓰는 게 낫다
