dandacompany Kiwoom Broker
키움증권 공식 CLI를 증권사 어댑터로 사용한다. 인증·토큰·API 필드 매핑은 CLI에 맡기고, 이 스킬은 명령 선택과 안전 경계를 담당한다.
실행 전 점검
설치한 일반 터미널과 Hermes 세션의 PATH·HOME·Keyring은 다를 수 있다. 따라서 조회나 주문 전에 현재 Hermes 세션 안에서 아래 preflight를 수행한다.
command -v kiwoomcli로 실행 파일을 찾는다.없으면
$HOME/.local/bin/kiwoomcli가 실행 가능한지 확인한다. 이 폴백이 성공하면 해당 세션의 PATH 문제로 보고하고 절대 경로로 실행한다.둘 다 없으면 실행하지 말고 다음 설치 명령을 안내한다.
uv tool install kwcli uv tool update-shell초기 설정이 없다면 사용자가 직접 대화형 터미널에서
kiwoomcli setup을 실행하게 한다. setup은 Hermes와 같은 호스트·같은 OS 사용자에서 해야 한다. 강의 실습에서는 서버demo, 계좌 별칭모의계좌를 선택한다. App Key와 Secret은 OS 자격 증명 저장소에 보관하며.env파일을 만들지 않는다.setup이
자격 증명 저장소 사용 불가를 보고하면 지원되는 Keyring 백엔드가 없는 것이다..env를 임의로 만들어 우회하지 말고 중단한 뒤 사용자에게 보고한다.kiwoomcli auth status --profile 모의계좌와kiwoomcli doctor를 실행한다. 자유롭게 해석하지 말고 상태 출력에서 다음 레이블의 값을 그대로 옮긴다:계좌 별칭,모드,자격 증명 존재,자격 증명 출처,토큰 유효,지금 API 호출 가능. 값이 서로 모순되거나지금 API 호출 가능: 예가 아니면 조회나 주문으로 넘어가지 않는다.강의 실습에서는
demo프로필만 사용한다.real전환은 사용자가 실계좌 사용을 명시적으로 요청하고 별도 운영 승인을 제공한 경우에만 검토한다.
자격증명, 접근토큰, 계좌번호 원문을 출력하거나 로그에 남기지 않는다. 토큰 발급 엔드포인트를 직접 호출하지 않는다.
조회
항상 구조화된 출력을 요청하고, 원문 전체를 그대로 재출력하지 말고 요청에 필요한 필드만 요약한다.
kiwoomcli domestic etfs info --code 069500 --profile 모의계좌 --format json
kiwoomcli domestic candles daily --code 069500 --date YYYYMMDD --profile 모의계좌 --format json
kiwoomcli domestic accounts holdings --basis total --exchange KRX --profile 모의계좌 --format json
명령이나 옵션을 확신할 수 없으면 추정하지 말고 먼저 찾는다.
kiwoomcli spec search "검색어"
kiwoomcli domestic etfs info -h
return_code가 0인지 확인한다. 성공 코드가 아니거나 응답이 비어 있으면 값을 지어내지 말고 차단 원인과 다음 확인 명령을 보고한다.
주문
주문은 다음 두 단계로 분리한다.
1. 미전송 미리보기
사용자가 매수·매도를 요청해도 처음에는 --confirm을 붙이지 않는다.
kiwoomcli domestic orders buy \
--code 069500 \
--qty 1 \
--price 90000 \
--order-type limit \
--profile 모의계좌 \
--format json
CLI가 주문은 아직 전송되지 않았습니다라고 확인한 경우에만 주문 초안으로 취급한다. 종목, 수량, 가격, 주문 유형, 모드를 사용자에게 다시 보여주고 승인을 요청한다.
2. 승인 후 집행
다음 조건을 모두 충족한 경우에만 같은 명령에 --confirm을 추가한다.
- 사용자가 방금 제시한 주문 초안을 명시적으로 승인했다.
- 승인 대상의 종목·수량·가격·주문 유형·모드가 미리보기와 동일하다.
- 상위 하네스가 요구하는
OrderIntent와ApprovalRecord가 존재한다. - 인증 프로필은
모의계좌이고 서버는demo다. 실계좌는 이 스킬의 강의 기본 범위가 아니다.
하나라도 다르면 집행하지 않는다. 승인 뒤 입력이 달라졌다면 새 미리보기를 만들고 다시 승인받는다.
금지 사항
curl이나 자체 Python으로 키움 REST API를 직접 호출하지 않는다.- 자체 토큰 캐시나 토큰 발급 명령을 만들지 않는다.
- 사용자의 명시적 승인 없이
--confirm을 붙이지 않는다. - 실패 응답을 성공처럼 요약하지 않는다.
- CLI의 기본 안전장치를 우회하지 않는다.
kiwoomcli는 브로커 호출 도구다. 전략 판단, 주문 의도 생성, 승인 기록, 중복 방지, 체결 대사는 magma-finance-lab 하네스가 담당한다.