Show GN: KIS-Agent — 한국투자증권 OpenAPI, 이제 pip 하나로

한국투자증권 OpenAPI 쓰려고 공식 문서 펼쳤다가 닫은 적 있으신 분들을 위해 만들었습니다.
인증 토큰 관리, Rate Limit 눈치보기, stck_prpr 같은 필드명 해독, 100건 페이지네이션 루프 — 이걸 매번 직접 짜는 게 맞나 싶어서 래퍼로 묶었습니다.

뭐가 되나요
터미널에서 바로:
bashkis price 005930 # 삼성전자 현재가
kis balance --holdings # 계좌 잔고 + 보유종목
kis overseas NAS AAPL # 나스닥 AAPL
코드에서:
pythonagent = Agent(app_key=..., app_secret=..., account_no=...)
price = agent.get_stock_price("005930")
agent.order_stock_cash("buy", "005930", "03", "1", "0") # 시장가 매수
LLM 에이전트 도구로:
JSON 출력 + kis schema 타입 탐색으로 GPT/Claude 툴콜에 바로 붙일 수 있습니다.

주요 해결 포인트

필드명 자동 변환 — stck_prpr → currentPrice. 공식 응답 그대로 받지 않아도 됩니다
Rate Limiting 내장 — 실측 기반 18 RPS / 900 RPM. 터지고 나서 조절할 필요 없음
캐싱 — 동일 요청 반복 시 API 호출 80~95% 감소
100건 제한 우회 — get_daily_price_all()로 전 기간 자동 수집
96개 TypedDict 모델 — IDE 자동완성, 타입 체커 전부 동작

지원 범위
국내 (KOSPI/KOSDAQ/NXT) · 해외 9개 거래소 (NASDAQ, NYSE, 도쿄, 상해, 홍콩, 베트남 등) · 국내외 선물옵션 · WebSocket 실시간 스트리밍 · 투자자/프로그램매매/증권사별 동향 분석

개인 트레이딩 자동화 목적으로 만들다 보니 실전에서 실제로 쓰는 것들 위주로 구현되어 있습니다. 공식 API에 있는데 빠진 기능은 이슈로 남겨주시면 추가하겠습니다.