openclaw/agents/stock/workspace/memory/2026-04-24.md

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 확보되면 즉시 덮어쓰는 게 낫다