키움증권 모의투자 API를 헤르메스에 연결하기

이번 유닛에서는 자산운용팀의 첫 외부 권한으로 키움증권 REST API를 연결합니다. 목표는 자동 주문이 아니라 사람이 한도를 먼저 확정하고, 키는 운영체제 Keyring에 보관한 뒤, Sam이 시세와 모의 잔고만 조회하는 환경을 만드는 것입니다.

이 실습은 교육용 모의투자 계좌만 사용합니다. 종목 추천이나 수익 보장을 다루지 않으며, 8.1에서는 주문을 실행하지 않습니다.

1. 먼저 준비할 것

아래 준비를 마친 뒤 시작하세요.

• 키움증권 계좌와 로그인 가능한 ID
• 키움 REST API 포털에서 API 사용 신청
• 상시모의투자 참가 신청과 모의투자용 App Key·Secret 발급
• Hermes의 Sam 프로필
• Git과 터미널

키움의 설치형 OpenAPI+는 Windows의 OCX/COM 방식입니다. 이번 수업에서 쓰는 것은 운영체제 제약이 적은 키움 REST API입니다. 공식 예제와 CLI 안내는 키움 REST API 공식 GitHub에서도 확인할 수 있습니다.

신청 화면은 바뀔 수 있으므로 메뉴 이름보다 순서를 기억하세요.

계좌 개설 → HTS ID 연결 → 상시모의투자 참가 신청
→ REST API 사용 신청(모의투자) → App Key·Secret 발급

App Key와 Secret은 문서, 채팅, .env 파일에 붙여넣지 않습니다. 뒤에서 실행할 kiwoomcli setup의 가려진 입력창에만 입력합니다.

2. 스타터 저장소 준비하기

Hermes 작업 폴더에 자산운용팀 스타터를 받습니다.

cd ~/.hermes/workspace
git clone https://github.com/dandacompany/magma-finance-lab.git
cd magma-finance-lab

이미 clone했다면 새로 받지 말고 기존 폴더로 이동하세요.

cd ~/.hermes/workspace/magma-finance-lab

이 폴더에서 Sam을 시작하면 저장소의 규칙과 PROMPTS.md, guardrails/limits.md를 같은 작업 문맥으로 사용할 수 있습니다.

3. 외부 권한보다 안전 기준을 먼저 확정하기

Sam에게 아래 메시지를 보냅니다.

오늘부터 자산운용팀을 개소한다. 너는 개발 담당으로 파견이야.
이 팀의 원칙 세 가지를 먼저 기억해줘.
1) 모든 거래는 모의투자 연습 계좌에서만 한다
2) 주문은 어떤 경우에도 내 승인 없이 실행하지 않는다
3) 앱키와 계좌 정보는 화면에 출력하지 않는다
확인했으면 원칙 세 가지를 한 줄씩 요약해서 답해줘.

그다음 guardrails/limits.md를 사람이 직접 엽니다. 예시 숫자를 자신의 모의투자 기준으로 검토하고, 모든 항목을 확인한 뒤에만 frontmatter의 상태를 바꿉니다.

status: confirmed
updated_by: human

예시 한도에는 시드머니와 주문 수량, 하루 기안 횟수, 보유 상한이 들어 있습니다. 손실 한도와 매수 금지 조건, 오류 시 중단 규칙도 함께 확인합니다. 에이전트에게 이 숫자를 정하거나 confirmed로 바꾸게 하지 마세요.

이 순서가 중요한 이유는 간단합니다. 자격 증명을 먼저 연결하고 한도를 나중에 붙이면 안전장치가 선택 사항처럼 취급됩니다.

4. 키움 공식 CLI 설치하기

kwcli는 키움증권이 제공하는 공식 CLI 패키지이고, 실행 명령은 kiwoomcli입니다. uv가 없다면 함께 설치합니다.

command -v uv >/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
uv tool install kwcli
uv tool update-shell
uv tool list

목록에서 kwcli가 보이면 setup 마법사를 실행합니다.

kiwoomcli setup

마법사에서는 다음 기준을 지킵니다.

1. 서버는 demo를 선택합니다.
2. 계좌 별칭은 모의계좌로 둡니다.
3. App Key와 Secret은 가려진 입력창에만 붙여넣습니다.
4. 입력 중 커서가 움직이지 않아도 다시 여러 번 붙여넣지 않습니다.
5. 검증과 OS 자격 증명 저장소 저장까지 완료합니다.

설정 직후 일반 터미널에서 상태를 확인합니다.

kiwoomcli auth status --profile 모의계좌
kiwoomcli doctor

WSL에서 자격 증명 저장소 오류가 날 때

macOS에서는 보통 Keychain을 바로 사용합니다. WSL에서 사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다와 비슷한 메시지가 나오면 Secret Service 백엔드를 먼저 준비합니다.

sudo apt update
sudo apt install -y gnome-keyring libsecret-tools
eval "$(gnome-keyring-daemon --start --components=secrets)"
gnome-keyring-daemon --unlock

마지막 명령이 암호를 요청하면 현재 WSL 사용자의 Keyring 암호를 입력합니다. 암호나 App Key를 명령문에 직접 적지 마세요. 같은 WSL 로그인 세션에서 kiwoomcli setup을 다시 실행하고, 불완전한 모의계좌 프로필이 보이면 App Key·Secret 재입력 경로를 선택합니다.

Keyring 사용 가능이라는 문구만으로는 완료가 아닙니다. 실제 저장, auth status, API 검증까지 이어져야 통과입니다.

5. 새 Sam 세션에서 preflight 통과하기

uv tool update-shell과 Keyring 준비는 이미 실행 중이던 Hermes 세션에 바로 반영되지 않을 수 있습니다. 기존 Sam을 종료하고 같은 프로젝트 폴더에서 새 세션을 시작합니다.

cd ~/.hermes/workspace/magma-finance-lab
hermes -p sam

새 Sam 세션에 아래 읽기 전용 점검을 요청합니다.

읽기 전용 환경 점검만 해줘.
1) command -v kiwoomcli
2) kiwoomcli auth status --profile 모의계좌
3) kiwoomcli doctor
자격 증명·토큰·계좌번호 원문은 출력하지 마. `command -v` 결과로 PATH 인식 여부를 적고, `auth status` 출력의 `계좌 별칭`, `모드`, `자격 증명 존재`, `자격 증명 출처`, `토큰 유효`, `지금 API 호출 가능` 값을 해석하거나 번역하지 말고 그대로 옮겨줘. 값이 모순되면 통과로 판정하지 마.

다음 값이 모순 없이 확인되어야 합니다.

값이 서로 모순되면 Sam의 요약을 믿고 넘어가지 말고 공식 CLI 출력을 다시 확인하세요.

6. Sam에 kiwoom-broker 스킬 설치하기

일반 터미널에서 Sam 프로필에 운영 스킬을 설치합니다.

hermes -p sam skills install dandacompany/dante-skills/kiwoom-broker --yes
hermes -p sam skills list

이미 열어 둔 Sam 세션에서는 /reload-skills를 실행해 새 스킬을 다시 불러옵니다.

kiwoom-broker는 증권사 연결을 새로 구현하는 코드가 아닙니다. 공식 kiwoomcli의 명령을 고르고, demo 여부와 JSON 응답을 확인하고, 승인 전 주문 확정을 막는 운영 지침입니다.

7. KODEX 200과 모의 잔고만 조회하기

Sam에게 아래 메시지를 보냅니다.

kiwoom-broker 스킬과 키움 공식 CLI의 `모의계좌` 프로필을 사용해서

1) KODEX 200(069500)의 종목 정보를 조회하고
2) 모의투자 계좌 잔고를 조회해서 보여줘.

접근토큰·앱키·시크릿·계좌번호 값은 출력하지 마. 주문은 오늘 하지 않는다.

가격, 평가금액, 보유 수량은 조회 시점마다 달라질 수 있습니다. 특정 숫자가 영상과 다르다는 이유만으로 실패로 판단하지 마세요. 보유 종목이 없다면 모의투자 해당조회내역이 없습니다라는 안내도 정상입니다.

8. API 성공을 세 단계로 판정하기

에이전트의 자연어 요약만 보고 성공으로 판단하지 않습니다. 아래 세 단계를 순서대로 확인합니다.

1. HTTP 요청이 성공했는지 확인합니다.
2. 응답의 return_code가 0인지 확인합니다.
3. 요청한 종목 필드나 잔고 행이 실제 응답에 있는지 확인합니다.

잔고가 0건인 것과 API 호출 실패는 다릅니다. 0건이어도 HTTP와 return_code가 정상이고, 응답이 빈 보유 내역을 명시하면 성공한 조회입니다.

9. 이번 유닛의 완료 체크리스트

• 모든 실습이 모의투자 계좌인지 확인했다
• guardrails/limits.md를 사람이 검토하고 confirmed로 바꿨다
• App Key·Secret을 파일이나 채팅에 남기지 않았다
• kiwoomcli setup에서 demo와 모의계좌를 선택했다
• 새 Sam 세션에서 PATH·자격 증명·토큰 상태를 확인했다
• kiwoom-broker를 Sam에 설치했다
• KODEX 200과 모의 잔고만 조회했다
• 주문은 실행하지 않았다

자주 만나는 문제

다음 유닛

지금은 조회 결과가 화면에만 남아 있어 이전 상태와 비교할 수 없습니다. 8.2에서는 Supabase 시세 데이터베이스와 Kanban ETL을 구성해 조회 사실을 장부에 적재합니다.