한국투자증권 오픈API(KIS Developers)는 국내에서 가장 널리 쓰이는 증권사 API입니다. 문서도 예제도 많죠.
그런데 실계좌로 자동화를 몇 달 돌려보면, 문서 바깥의 세계를 만나게 됩니다. 오늘은 제가 실제로 밟은 함정 다섯 개와 우회법입니다.
하나같이 “API는 성공이라는데 현실은 아닌” 유형이라, 자동매매를 계획 중이라면 미리 알아두시는 게 좋습니다.
[30초 요약] ①해외 잔고가 거래소별로 중복 반환될 수 있고 ②체결내역 조회가 특정 조합에서 영구 오류를 내며(우회: 잔고 변화로 체결 판정) ③매도 지정가를 ‘현재가’로 걸면 체결이 안 되고 ④주문 취소는 전용 TR이 따로 있으며 ⑤해외 일봉의 ‘최신 날짜’는 한국 새벽 기준으로 어긋납니다.
함정 1 — 잔고가 두 배로 보인다
해외주식 잔고 조회가 어느 날 같은 종목을 두 줄로 돌려줬습니다. 수량을 합치면 실제 보유의 2배. 매수 로직이 이걸 보면 “이미 충분히 보유”로 판단하거나, 매도 로직이면 없는 수량을 팔려 들겠죠.
원인은 거래소별 중복 반환 — 같은 종목이 조회 조건에 따라 복수 거래소 레코드로 내려올 수 있습니다. 해법은 단순합니다. 심볼 기준으로 합산(중복 제거)하고 나서 로직에 넘기세요. 응답 리스트를 그대로 신뢰하면 안 됩니다.
함정 2 — 체결 조회만 영원히 죽는 계좌가 있다
제일 기괴했던 함정입니다. 해외주식 체결내역 TR을 호출하면 “처리계좌 ID와 사용자정보 상이”(APTR0058) 오류만 옵니다. 같은 키로 잔고 조회는 멀쩡한데, 체결내역만 무조건 실패합니다.
파라미터를 바꿔도, 날짜를 바꿔도 동일했습니다. 특정 앱키·계좌 조합에서 이 TR 자체가 안 되는 케이스가 존재한다는 결론에 도달했고요.
문제는 자동매매에서 체결 확인이 필수라는 점입니다. 주문을 냈는데 체결됐는지 모르면 다음 판단을 못 하니까요. 저희 초기 코드는 조회가 실패하면 “체결됐다고 가정”했는데 — 이게 유령 매매 기록을 만들었습니다. 팔리지도 않은 주식이 팔린 걸로 기록되고, 그 가정 위에서 다음 주문이 나갔습니다.
우회법은 주문 전후 잔고 비교입니다. 주문 직전 보유 수량을 찍어두고, 주문 후 잔고를 다시 조회해서 수량이 변했으면 체결, 그대로면 미체결. 체결내역 API 없이도 확실하게 판정됩니다.
함정 3 — 매도 지정가를 ‘현재가’로 걸면 안 팔린다
매도 주문이 자꾸 미체결로 끝나서 파봤더니, 시세 API가 주는 “현재가”가 문제였습니다. 그 값은 매수 쪽 호가에 가까워서, 그 가격으로 매도 지정가를 걸면 시장의 매수 대기가격보다 높게 걸립니다. 아무도 안 사주는 가격이죠.
매도는 매수 1호가(bid) 기준으로 걸어야 즉시 체결됩니다. 매수 주문은 반대로 매도 1호가(ask) 기준. 방향에 따라 참조할 호가가 다르다는 것 — 수동 매매에선 자연스러운 상식인데, 코드로 옮길 때 빠뜨리기 쉽습니다.
함정 4 — 취소는 취소 전용 TR로
미체결 주문을 취소하려고 조회용 TR ID로 요청을 보냈더니 “응답전문 구성 오류”가 왔습니다. 알고 보니 정정·취소는 전용 TR이 따로 있고, 취소 수량(잔량 전체) 지정 방식도 다릅니다.
TR ID를 잘못 짚으면 에러 메시지가 원인을 안 알려줘서 한참 헤맵니다. “조회 계열과 주문 계열은 TR이 다르다”를 기억해두세요.
함정 5 — ‘오늘’이 미국엔 아직 안 왔다
해외 일봉을 조회할 때 기준일을 오늘(한국 날짜)로 주면, 한국 새벽엔 빈 응답이 올 수 있습니다. 미국 장 기준으로는 아직 오지 않은 미래 날짜니까요. 해법은 응답이 빌 때 날짜를 하루씩 물려가며 재시도하는 것.
그리고 하나 더 — 받아온 “가장 최근 봉”이 정말 어제 것인지 날짜를 검증하세요. 데이터 반영이 늦어지면 그저께 봉이 최신인 척 내려오는데, 그걸 어제로 믿고 등락률을 계산하면 하루 묵은 신호로 매매하게 됩니다. 저는 이 검증을 뒤늦게 넣고 나서야 발 뻗고 자게 됐습니다.
다섯 함정의 공통 교훈
“API가 성공(200)을 반환했다”와 “내가 원한 일이 일어났다”는 다른 문장입니다.
돈이 걸린 자동화의 철칙은 하나였습니다 — 주문이든 조회든, 중요한 동작 뒤에는 반드시 상태를 다시 조회해서 현실을 확인할 것. 응답 코드를 믿지 말고 잔고를 믿으세요.
자주 묻는 질문
한투 API 체결내역 오류(APTR0058)는 어떻게 해결하나요? 저는 해결하지 못했고 우회했습니다(잔고 비교 판정). 같은 오류를 겪는 분이 있다면 키 재발급·고객센터 문의도 시도해볼 수 있지만, 어떤 경우든 잔고 비교 폴백은 넣어두시길 권합니다.
모의투자 계좌로 먼저 테스트하면 되지 않나요? 반드시 그렇게 하세요. 다만 모의와 실전은 TR ID가 다르고, 모의에서 안 나던 문제(호가·체결 지연)가 실전에서 나옵니다. 모의 통과는 시작이지 끝이 아닙니다.
해외주식 자동매매, 지정가와 시장가 중 뭐가 낫나요? 저는 지정가 기본 + 미체결 시 재주문 구조를 씁니다. 시장가는 급변동에서 체결가가 예상을 벗어날 수 있어서요. 대신 함정 3의 호가 방향을 반드시 지켜야 합니다.
이 함정들은 한투만의 문제인가요? 회사마다 함정의 종류가 다를 뿐 어디나 있습니다. 토스증권 쪽 함정은 별도 글로 정리했습니다.
함께 읽으면 좋은 글
다른 증권사의 함정 지도는 토스증권 OpenAPI 실전 가이드에서 이어집니다. 이런 자동화를 어떤 서버에서 어떤 안전장치로 돌리는지는 라즈베리파이 자동화 서버 구축기에 담았습니다.
자동매매의 적은 시장이 아니라 “성공했다고 믿은 실패”였습니다 — 확인하는 코드가 수익 코드보다 먼저입니다.
※ 본 글은 실측 경험 기준이며 API 사양은 변경될 수 있습니다. 특정 증권사·상품의 권유가 아닙니다.