플랫폼
키움증권 신 REST
미국주식 시세 TR
미국주식 시세 TR
키움 REST 미국주식 보유종목 감시 + AI 뉴스·공시 분석 알림
미국장은 우리 시간으로 밤 열 시 반에 열려서 새벽 다섯 시에 닫힙니다. 의뢰인은 "매매는 내가 할 테니, 내 종목에 무슨 일이 생기면 PC가 깨워 달라"고 했습니다. 그래서 이 프로그램에는 주문 기능이 없습니다. 보유종목 열 개까지의 시세와 RSI, 수익률을 보고, 4시간마다 뉴스와 공시를 AI로 읽어 점수를 매기고, 조건이 맞으면 Windows 트레이 팝업과 소리로 알립니다. 2026년 9월 납품, 이후 고객 피드백 두 건을 반영해 v1.2.
01알림 규칙
| 유형 | 조건 | 비고 |
|---|---|---|
| 추가매수 | RSI(14, 5분봉) ≤ 30 | 기본 켜짐 |
| 추가매수(하락) | 전일 대비 ≤ −5% | 기본 꺼짐, 선택 |
| 익절 | 수익률 ≥ +10% | 매수단가는 직접 입력 |
| 손절 | 수익률 ≤ −5% | |
| AI 분석 | 4시간마다 뉴스 + 공시 → 점수 −100~+100, 영문 3줄 | 새 소식 0건이면 호출 생략 |
같은 종목·같은 유형은 30분 안에 다시 알리지 않고, 이 쿨다운은 프로그램을 껐다 켜도 유지됩니다. 알림 허용 시간대도 둘 수 있습니다. 미국 정규장이 우리 새벽이라 "새벽 2시~5시는 소리 끄기" 같은 설정이 실제로 필요했습니다.
처음엔 정규장 밖에서는 시세 폴링 자체를 쉬게 했더니 고객이 "현재가가 안 보인다"고 물어보셨습니다. 표시는 항상 갱신(장외 60초)하고, 알림 판정만 시간 게이트를 타도록 나눴습니다.
02키움 미국주식 TR은 문서에 없었다
착수할 때 가장 큰 위험은 키움 REST의 미국주식 TR이 한글 가이드에 안 나온다는 점이었습니다. 국내주식 명명 규칙(ka 접두사, /api/dostk/*)에서 유추해 먼저 만들어 봤는데,
실키로 돌리자 전부 1504: 해당 URI에서는 지원하는 API ID가 아닙니다로 거부됐습니다.
답은 키움 공식 GitHub 저장소의 examples/미국주식/ 샘플에 있었습니다. 실계좌 응답으로 확인한 값입니다.
| 용도 | api-id | endpoint | 메모 |
|---|---|---|---|
| 현재가 | usa20100 | /api/us/mrkcond | cur_prc에 부호 포함 |
| 분봉 | usa06011 | /api/us/chart | 최신→과거 정렬, 뒤집어야 함 |
| 일봉 | usa06012 | /api/us/chart | 시각 필드가 dt |
| 종목 리스트 | usa10099 | /api/us/stkinfo | 약 1.9만 종목, 거래소 포함 |
미검증 상수를 파일 상단 dict 하나에 모아 두고 FIXME를 붙여 둔 덕에, 실제 값을 확인한 뒤 한 파일만 고치고 끝났습니다.
착수 첫날 여섯 API를 한 번에 찍어 보는 검증 스크립트(tools/verify_api.py)를 먼저 만든 것도 왕복을 한 번으로 줄였습니다.
값은 바뀔 수 있으니 실제 개발 시엔 공식 저장소로 다시 확인하셔야 합니다.
AAPL은 되는데 KO는 안 됐다
미국주식 TR은 종목의 거래소구분(stex_tp: ND 나스닥 / NY 뉴욕 / NA 아멕스)이 정확해야 조회됩니다. 틀리면 1903 조회 내역이 없습니다.
전체(%)는 종목 리스트 TR에서만 통합니다. 그래서 종목 리스트로 티커→거래소 맵을 받아 하루 캐시하고, 없는 종목은 ND→NY→NA 순으로 시도한 뒤 성공값을 기억합니다.
셋 다 실패하면 오류코드 대신 "나스닥·뉴욕·아멕스에서 찾을 수 없는 종목입니다. 티커를 확인하세요"로 바꿔 보여 줍니다.
한투 프리마켓 손절 봇에서 겪은 것과 같은 구조의 함정입니다.
03납품 후에 생긴 일
- AI 모델이 은퇴했는데 개발자 키는 멀쩡했다 — 고객만
404: This model … is no longer available to new users를 받았습니다. Google이 구모델을 은퇴시킬 때 기존 키는 유예하고 신규 키만 즉시 막기 때문에 개발 환경에서는 재현이 안 됩니다. 404 본문에 적힌 대체 모델명을 파싱해 자동 전환하고 설정에 저장, 파싱 실패 시 항상 최신을 가리키는 별칭으로 폴백하도록 고쳤습니다. 외부 AI를 쓰는 프로그램은 모델 은퇴를 정상 이벤트로 설계해야 한다는 걸 배웠습니다. - 통신 오류 한 번에 종목 하나가 4시간 방치됐다 — 키움 시세 호출에는 재시도가 있었는데 Gemini·Finnhub·EDGAR에는 없었습니다. 실측 응답 시간이 평균 4.8초라 60초 타임아웃 초과는 모델 지연이 아니라 순간 장애였고, 재시도가 정답이었습니다. 키 오류와 429는 재시도에서 빼서 무료 한도를 아낍니다.
- [종료]를 눌러도 프로세스가 살아남았다 — 트레이 상주 때문에 마지막 창이 닫혀도 종료하지 않게 해 둔 상태에서, 종료 경로가 창만 닫고 이벤트 루프를 끝내지 않았습니다. 기능은 멈췄는데 껍데기만 남는 좀비. 명시적 종료 호출을 넣고, 그 짝이 빠지면 실패하는 검사를 테스트에 넣었습니다.
04납품 직전에 잡은 것 네 가지
수용 테스트 15건이 전부 통과한 상태에서 보안·안정성만 따로 한 번 더 봤습니다. 정상 경로가 아니라 예외·동시성·강제 종료 경로에서 넷이 나왔습니다.
- API 키 평문 유출 경로 — 네트워크가 한 번 끊기면 예외 메시지에 요청 URL(쿼리 포함)이 통째로 들어갑니다. 키를 쿼리로 보내면 로그·CSV·상태 파일·화면 네 곳에 남고, 설명서가 "문의 시 로그를 보내 주세요"라고 안내하니 AS 절차가 곧 키 유출 절차가 됩니다. 헤더 전송 + 기록 직전 마스킹으로 바꿨습니다.
- 설정 손상 시 첫 알림에서 즉사 — 시각 문자열이
"9"처럼 깨져 있으면 기동은 되는데 첫 알림에서 죽습니다. 파싱 실패 시 열어 두는(fail-open) 쪽으로. - 스레드 경합 — 쿨다운 dict를 워커와 GUI가 락 없이 공유. 종목 삭제 중 평가가 돌면 재현됐습니다.
- 강제 종료 시 종목 목록 소실 — truncate 후 쓰기라 저장 중에 꺼지면 빈 파일. 임시 파일 → fsync → 교체로.
.env를 손으로 고치지 않아도 되게 했습니다05납품물 · 기술
- Windows 단일 실행 파일(
--onefile, 약 41MB), 트레이 상주, 단일 인스턴스 강제(중복 실행 시 키움 토큰이 서로 무효화되는 걸 막기 위해) - API 키 GUI 입력창, 종목 추가/삭제, 알림 설정, 알림 이력 CSV
- 테스트 115개 + 실키 수용 테스트 T1~T11(익절·손절 실제 발화, 네트워크 차단·복구 포함) + 10종목 3분 연속 폴링 140회 부하 확인
- 버전 단일 소스 → 창 제목·로그·zip 이름·소스 백업 자동 연동
키움증권 신 REST API (미국주식)
Finnhub · SEC EDGAR
Google Gemini (REST 직접 호출)
Python 3.10 64bit · PyQt5
순수 Python RSI (pandas 없음)
PyInstaller --onefile
06관련 사례 · 더 보기
키움 REST 자체가 처음이면 키움 REST API 자동매매 가이드와 앱키 발급 가이드부터 보시면 됩니다.
※ 본 사례는 고객 요구사항을 익명 처리하여 재구성한 것이며, 화면의 종목·가격·점수는 예시값입니다. AI 분석 점수는 뉴스 요약일 뿐 매수·매도 추천이 아닙니다.
알고랩은 매매 자동화 프로그램 제작 서비스이며, 종목 추천·투자 자문·수익 보장 서비스가 아닙니다.
이런 프로그램, 바로 견적 받아보세요
주문 없이 알림만 원하시면 그렇게 말씀해 주세요. 범위가 줄면 기간과 비용도 줍니다.
알고랩이 24시간 빠르게 답변드립니다.