플랫폼
키움증권 신 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이 한글 가이드에 나오지 않는다는 점이었습니다. 국내주식의 이름 규칙에서 유추해 먼저 만들어 봤는데, 실제 키로 돌리자 전부 지원하지 않는 API라는 오류로 거부됐습니다.
답은 키움 공식 GitHub 저장소의 미국주식 샘플에 있었습니다. 아래는 실계좌 응답으로 확인한 값입니다.
| 용도 | api-id | endpoint | 메모 |
|---|---|---|---|
| 현재가 | usa20100 | /api/us/mrkcond | cur_prc에 부호 포함 |
| 분봉 | usa06011 | /api/us/chart | 최신부터 과거 순, 뒤집어야 함 |
| 일봉 | usa06012 | /api/us/chart | 시각 필드가 dt |
| 종목 리스트 | usa10099 | /api/us/stkinfo | 약 1.9만 종목, 거래소 포함 |
확인하지 못한 값들은 처음부터 한 곳에 모아 두었기 때문에, 실제 값을 확인한 뒤에는 파일 하나만 고치면 됐습니다. 착수 첫날 여섯 가지 API를 한꺼번에 호출해 보는 검증 스크립트를 먼저 만든 것도 도움이 됐습니다. 값은 바뀔 수 있으니 실제 개발 때는 공식 저장소로 다시 확인하셔야 합니다.
AAPL은 되는데 KO는 안 됐습니다
미국주식 TR은 종목의 거래소 구분(ND 나스닥, NY 뉴욕, NA 아멕스)이 정확해야 조회됩니다. 틀리면 조회 내역이 없다는 오류가 납니다. 그래서 종목 리스트에서 티커별 거래소를 받아 하루 동안 저장해 두고, 거기 없는 종목은 나스닥, 뉴욕, 아멕스 순으로 시도해서 성공한 값을 기억합니다. 셋 다 실패하면 오류 코드를 그대로 내보내지 않고, 티커를 확인하라는 안내 문구로 바꿔 보여 줍니다. 한투 프리마켓 손절 봇에서도 같은 종류의 문제를 겪었습니다.
03납품 후에 생긴 일
- 고객 쪽에서만 AI 모델을 쓸 수 없다는 404 오류가 났습니다. Google은 구모델을 종료할 때 기존 키는 한동안 유예하고 신규 키만 바로 막습니다. 그래서 개발 환경에서는 재현되지 않았습니다. 오류 응답에 적힌 대체 모델 이름을 읽어 자동으로 전환하고 설정에 저장하게 고쳤습니다. 이름을 읽지 못하면 항상 최신 모델을 가리키는 별칭을 씁니다. 외부 AI를 쓰는 프로그램은 모델 종료를 언젠가 오는 일로 보고 만들어야 한다는 것을 배웠습니다.
- 통신 오류 한 번에 종목 하나가 4시간 동안 분석되지 않은 일도 있었습니다. 키움 시세 호출에는 재시도가 있었는데 Gemini, Finnhub, EDGAR 호출에는 없었습니다. 실측 응답 시간이 평균 4.8초였으니 60초 타임아웃을 넘긴 것은 일시적인 장애였고, 다시 시도하면 되는 문제였습니다. 키 오류와 호출 한도 초과는 재시도하지 않아 무료 한도를 아낍니다.
- 종료를 눌러도 프로세스가 남아 있었습니다. 트레이에 상주시키려고 마지막 창이 닫혀도 종료되지 않게 해 두었는데, 종료 버튼이 창만 닫고 프로그램 자체는 끝내지 않았던 것입니다. 종료 처리를 넣었고, 그 처리가 빠지면 실패하는 검사를 테스트에 추가했습니다.
04납품 직전에 잡은 문제
수용 테스트 15건이 모두 통과한 상태에서 보안과 안정성만 따로 한 번 더 봤습니다. 오류가 났을 때, 여러 작업이 동시에 돌 때, 강제로 종료됐을 때를 살펴보니 네 건이 나왔습니다.
- 네트워크가 끊기면 오류 메시지에 요청 주소가 통째로 들어갑니다. API 키를 주소에 붙여 보내면 로그, CSV, 상태 파일, 화면 네 곳에 키가 남습니다. 설명서에는 문의할 때 로그를 보내 달라고 적혀 있으니, AS를 받다가 키가 새는 셈입니다. 키를 헤더로 보내고, 기록하기 직전에 가리도록 바꿨습니다.
- 설정 파일의 시각 값이
"9"처럼 깨져 있으면 실행은 되는데 첫 알림에서 프로그램이 죽었습니다. 값을 읽지 못하면 알림을 허용하는 쪽으로 처리했습니다. - 알림 간격 기록을 백그라운드 작업과 화면이 동시에 건드리는 문제가 있었습니다. 종목을 삭제하는 중에 판정이 돌면 재현됐습니다.
- 저장 중에 강제 종료되면 종목 목록 파일이 비어 버렸습니다. 임시 파일에 먼저 쓰고 나서 교체하는 방식으로 바꿨습니다.
05납품물과 기술
- Windows 단일 실행 파일(약 41MB)이고 트레이에 상주합니다. 중복 실행하면 키움 토큰이 서로 무효화되므로 하나만 실행되게 했습니다.
- API 키 입력창, 종목 추가와 삭제, 알림 설정, 알림 이력 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 분석 점수는 뉴스 요약일 뿐 매수나 매도 추천이 아닙니다.
알고랩은 매매 자동화 프로그램 제작 서비스이며, 종목 추천, 투자 자문, 수익 보장 서비스가 아닙니다.
알림만 받는 프로그램도 만듭니다
주문 없이 알림만 원하시면 그렇게 말씀해 주세요. 범위가 줄면 기간도 줄어듭니다.
어떤 종목을 어떤 조건으로 보고 싶은지 알려 주시면 됩니다.