자동매매 프로그램 첫 실행 오류 — 납품 당일 막히는 7곳

1. 어디서 멈췄는지부터 — 3갈래

토요일 오전, 프로그램 압축 파일을 받은 김 대표님이 바탕화면에 풀고 두 번 클릭했습니다. 파란 창이 뜨고 끝입니다. 이런 상황에서 "프로그램이 안 돼요"라고만 보내면 원인을 찾는 데 하루가 갑니다. 먼저 어느 단계에서 멈췄는지만 구분하면 7곳 중 두세 곳으로 좁혀집니다.

B처럼 창이 순식간에 꺼지면 메시지를 읽을 수가 없습니다. 프로그램 폴더의 logs 폴더(이름은 제작자마다 다름)에 날짜별 로그 파일이 있으면 그걸 열어 마지막 줄을 보면 되고, 없다면 폴더 주소창에 cmd를 입력해 명령 프롬프트를 연 뒤 실행 파일 이름을 직접 쳐서 실행하면 창이 닫히지 않고 메시지가 남습니다.

2. 막히는 7곳과 고치는 법

① 윈도우가 실행을 막는다 — SmartScreen·백신

맞춤 제작한 .exe는 서명 인증서가 없는 경우가 많아 처음 실행할 때 이런 파란 창이 뜹니다.

Windows의 PC 보호
Microsoft Defender SmartScreen에서 인식할 수 없는 앱의 시작을 차단했습니다.
이 앱을 실행하면 PC가 위험에 노출될 수 있습니다.
                                   [실행 안 함]

제작자에게서 직접 받은 파일이 맞다면 추가 정보 → 실행을 누르면 됩니다. 더 곤란한 경우는 아무 창도 없이 파일이 사라지는 것인데, Microsoft Defender나 V3 같은 백신이 PyInstaller로 묶은 실행 파일을 오탐해 격리한 경우입니다. 원인과 예외 등록 방법은 PyInstaller exe 백신 오탐 글에 정리돼 있습니다. 출처를 모르는 파일이라면 이 단계에서 멈추는 게 맞습니다.

② 소스로 받았는데 파이썬이 없다

.py 소스와 requirements.txt로 납품받은 경우입니다. 명령 프롬프트에서 실행했을 때 이 문장이 나오면 파이썬이 설치되지 않았거나 PATH에 없는 것입니다.

'python'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는
배치 파일이 아닙니다.

윈도우 10·11에서는 파이썬이 없을 때 python을 치면 Microsoft Store가 열리기도 합니다. 제작자가 지정한 버전을 python.org에서 설치하고 설치 첫 화면의 Add python.exe to PATH를 체크하십시오. 그다음 pip install -r requirements.txt를 빼먹으면 ModuleNotFoundError: No module named 'dotenv'처럼 라이브러리 이름이 들어간 오류가 납니다. 버전이 너무 새것이어도 일부 라이브러리가 설치되지 않으니, 납품 문서에 적힌 버전을 따르는 것이 가장 안전합니다.

③ 설정 파일 이름이 .env.txt가 됐다

앱키와 계좌번호는 보통 .env나 config.yaml 같은 설정 파일에 따로 넣게 만듭니다(코드에 키를 박지 않기 위해서입니다). 메모장으로 .env를 만들고 저장하면 파일 형식이 '텍스트 문서'로 잡혀 실제 이름이 .env.txt가 되는데, 윈도우 탐색기는 확장자를 숨기므로 겉보기엔 멀쩡합니다. 탐색기 보기 → 표시 → 파일 확장명을 켜서 확인하고, 저장할 때 형식을 '모든 파일'로 바꾸십시오. 내용은 이런 모양입니다(값은 예시).

# .env — 따옴표·공백 없이, 등호 양옆도 붙여서
KIWOOM_APPKEY=발급받은앱키를그대로
KIWOOM_SECRETKEY=발급받은시크릿키를그대로
KIWOOM_MODE=mock

키를 복사할 때 앞뒤에 공백이나 줄바꿈이 딸려 오는 경우도 흔합니다. 증권사 홈페이지에서 더블클릭으로 선택하면 끝 글자가 빠지기도 하니 길이를 한 번 맞춰 보십시오.

④ 실전 키와 모의 키가 섞였다

가장 많이 걸리는 곳입니다. 증권사는 실전투자와 모의투자의 앱키·주소·주문 코드를 전부 따로 둡니다. 한국투자증권 공식 저장소(open-trading-api)의 설정 샘플 kis_devlp.yaml을 보면 구조가 한눈에 보입니다.

#실전투자
my_app: "앱키"
my_sec: "앱키 시크릿"

#모의투자
paper_app: "모의투자 앱키"
paper_sec: "모의투자 앱키 시크릿"

#domain infos
prod: "https://openapi.koreainvestment.com:9443" # 서비스
vps: "https://openapivts.koreainvestment.com:29443" # 모의투자 서비스

모의투자로 시험하려면 KIS 모의투자를 따로 신청해 모의용 앱키를 받아야 하고, 주문 코드도 다릅니다. 현금 매수 주문의 tr_id가 실전은 TTTC0012U, 모의는 VTTC0012U입니다(공식 예제 order_cash.py). 키움 REST API는 섞어 쓰면 오류 번호로 바로 알려 줍니다.

8030  투자구분(실전/모의)이 달라서 Appkey를 사용할수가 없습니다
8031  투자구분(실전/모의)이 달라서 Token를 사용할수가 없습니다
8104  모의투자에서 지원하지 않는 API 입니다.

(키움 공식 명세 kiwoom_api_spec.json의 error_codes 원문.) 8104는 설정이 틀린 게 아니라 그 기능 자체가 모의투자에 없다는 뜻이라, 실전에서만 확인할 수 있습니다. 실전으로 넘어갈 때 바꿔야 할 항목 목록은 KIS 모의→실전 전환 글에 있습니다.

⑤ 계좌번호를 한 칸에 다 넣었다

한국투자증권 계좌번호는 10자리지만 API는 앞 8자리(CANO)와 뒤 2자리(ACNT_PRDT_CD)를 나눠 받습니다. 위 샘플에서도 my_acct_stock: "증권계좌 8자리"와 my_prod: "01" # 종합계좌가 따로입니다. 하이픈을 넣거나 10자리를 한 칸에 넣으면 조회부터 실패합니다. 뒤 2자리는 종합계좌 01, 국내선물옵션 03, 개인연금 22처럼 계좌 종류마다 다르니 자세한 건 CANO·ACNT_PRDT_CD 글을 보십시오.

⑥ 이 PC의 IP가 등록되지 않았다

키움 REST API는 앱키를 받을 때 접속할 PC의 공인 IP를 등록해야 하고(포털 '계좌 App Key 관리', 최대 10개), 다른 곳에서 붙으면 이 번호가 납니다.

8010  Token을 발급받은 IP와 서비스를 요청한 IP가 동일하지 않습니다

흔한 경우는 세 가지입니다. 집에서 등록하고 사무실에서 켰을 때, 공유기를 재부팅해 통신사가 IP를 바꿨을 때, 그리고 VPS(원격 서버)에 올렸는데 내 PC IP만 등록했을 때입니다. VPS에서 돌린다면 그 서버의 IP를 등록해야 합니다. 등록 화면은 키움 REST API 앱키 발급 가이드 STEP 3에 그림으로 있습니다.

⑦ 어제는 됐는데 오늘 안 된다 — 토큰

앱키는 한 번 받아 계속 쓰는 값이고, 실제 호출에는 그 키로 받은 접근 토큰을 씁니다. 한국투자증권 공식 코드 kis_auth.py의 주석은 토큰을 "유효시간 1일, 6시간 이내 발급신청시는 기존 토큰값과 동일, 발급시 알림톡 발송"이라고 적고 있습니다. 하루가 지나면 만료되고, 만료된 토큰으로 부르면 msg_cd EGW00123이 옵니다. 공식 샘플도 이 코드를 보고 재발급합니다.

# open-trading-api legacy/rest/current_price_samle.py
    # 토큰 만료 시
    elif res.status_code == 200 and res.json()["msg_cd"] == "EGW00123" :
        auth()
        get_current_price(stock_no)

제대로 만든 프로그램이라면 이 재발급을 스스로 합니다. 그런데 카카오톡으로 'KIS 접근토큰 발급' 알림이 하루에 수십 번 온다면 프로그램이 토큰을 저장하지 않고 매번 새로 받고 있다는 뜻이니 제작자에게 알리십시오. 키움에서는 8005 Token이 유효하지 않습니다가 같은 상황입니다. 구조는 KIS 토큰 만료·재발급 글에 있습니다.

3. 오류 번호 빠른 표

KIS의 다른 EGW 코드(예: 호출 한도 EGW00201)는 KIS API 에러코드 글, 키움의 1xxx·8xxx 전체는 키움 return_code 글에 있습니다. 여기 없는 번호라면 설정보다는 프로그램 쪽일 가능성이 높으니 다음 절대로 보내 주시면 됩니다.

4. 제작자에게 보낼 것, 보내면 안 되는 것

위 7곳을 확인해도 안 되면 그때부터는 제작자의 일입니다. 아래 세 가지만 있으면 대부분 한 번에 원인이 나옵니다.

1. 화면 캡처 — 오류 창 또는 명령 프롬프트에 남은 메시지 전체
2. 로그 파일 마지막 30줄쯤 — 날짜 붙은 .log 파일을 메모장으로 열어 끝부분 복사
3. 실행 환경 — 실전인지 모의인지, 내 PC인지 VPS인지, 증권사(키움·한국투자증권 등)

첫날 켜는 데 성공했다면 다음은 며칠 동안 지켜보는 단계입니다. 무엇을 언제 확인하는지는 자동매매 봇 배포 후 첫 30일 글에 이어집니다. 이 글은 실행 설정을 다루며 특정 종목이나 수익을 약속하지 않습니다. 증권사 화면과 오류 문구는 바뀔 수 있으니 각 증권사 공식 안내를 함께 확인하십시오.

5. 자주 묻는 질문