한투 API로 자동매매 (앱키 발급, REST방식, 자동화)

한국투자증권 앱의 예약 매수·매도 기능은 최대 한 달 밖에 설정이 안 됩니다. 이 사실을 알게 된 날, 저는 바로 오픈API 포털을 뒤지기 시작했습니다. 소액으로 원칙 매매를 꾸준히 이어가고 싶었는데, 한 달 제한이 발목을 잡으니 직접 만들어 보자는 생각이 들었던 거죠. 그렇게 한국투자증권 오픈API를 이용한 개인용 자동매매 프로그램 제작기를 시작하게 되었습니다.

앱키 발급과 REST 방식 이해하기

한국투자증권 오픈API를 쓰려면 먼저 appkey와 appsecret, 즉 보안코드를 발급받아야 합니다. 보안코드란 API 호출 시 본인 인증을 위해 사용하는 고유 식별자 쌍으로, 이 두 값이 있어야 접근토큰(access_token)을 발급받을 수 있습니다. 접근토큰이란 실제 API 요청 시 HTTP 헤더에 담아 보내는 임시 인증값으로, 쉽게 말해 대문을 열어주는 열쇠 같은 개념입니다.

처음에 이 인증 구조를 이해하는 데 생각보다 시간이 걸렸습니다. 문서를 읽으면서 “이걸 매번 재발급해야 하나?” 싶었는데, 직접 써봤더니 토큰 만료 시점을 체크해서 자동으로 재발급하도록 로직을 짜 두면 거의 손 안 가도 됩니다. API 호출 방식은 크게 두 가지입니다.

  1. REST 방식: 주문(POST)과 조회(GET)에 사용. 엔드포인트(endpoint)란 API 요청이 도달하는 특정 URL 주소를 말하며, 실전 투자는 https://openapi.koreainvestment.com:9443, 모의투자는 https://openapivts.koreainvestment.com:29443 으로 나뉩니다.
  2. Websocket 방식: 실시간 시세나 체결 통보처럼 서버가 먼저 데이터를 밀어주는 방식. 이때는 접근토큰 대신 실시간 접속키(approval_key)를 별도로 발급받아야 합니다.

저는 실시간 데이터가 따로 필요 없었기 때문에 REST 방식만 사용했습니다. TLS 1.2 이상의 보안 프로토콜만 지원한다는 점도 확인이 필요한데, TLS란 인터넷 통신 구간을 암호화하는 보안 계층 기술입니다. 참고로 2025년 12월 12일 이후에는 TLS 1.0과 1.1 프로토콜 지원이 완전히 종료되므로(출처: 한국투자증권 오픈API 포털), 지금 당장 구현하는 분들은 처음부터 TLS 1.2 이상으로 맞춰두는 게 낫습니다.

crond로 자동화, 그리고 부분 체결 문제

프로그램 구조 자체는 복잡하지 않았습니다. 종목 코드와 초기 희망 매수가를 입력하면, 제가 정해둔 규칙에 따라 추가 매수가와 매도가가 자동으로 계산됩니다. 예를 들어 -10% 하락 시마다 정해진 금액을 추가 매수하고, +40% 도달 시 보유 수량의 절반을 매도하는 식입니다. 웹 통신은 curl로 처리했고, Ubuntu의 crond를 이용해 매일 아침 9시 장 시작 시점에 해당 가격으로 예약 주문이 자동으로 걸리도록 했습니다.

crond란 리눅스 계열 OS에서 특정 시각에 명령어를 자동 실행해 주는 스케줄러입니다. 서버를 따로 건드릴 필요 없이 설정 파일(crontab)에 시간과 실행 스크립트만 등록해 두면 되니, 자동화 입문자에게 꽤 편리한 도구입니다.

가장 머리를 썼던 부분은 부분 체결 처리였습니다. 부분 체결이란 매수 또는 매도 주문을 냈을 때 주문 수량의 일부만 시장에서 성사되고 나머지는 미체결로 남는 상황을 말합니다. 가령 절반만 팔리거나 절반만 사진 채로 장이 끝나면 다음 날 로직이 꼬일 수 있거든요. 이 부분은 DB에 체결 완료·미완료 상태를 구분하는 컬럼과 실제 체결 수량을 기록하는 컬럼을 따로 두는 방식으로 해결했습니다. 직접 겪어보니 이 컬럼 설계를 처음부터 꼼꼼히 잡아두는 게 나중 로직 수정 비용을 크게 줄여주더라고요.

API 응답 메시지 명세에는 HTTP Header와 Body가 모두 담겨 있는데, 체결 여부나 수량 같은 값은 Body 안에 있습니다. 응답 메시지 명세란 API 호출 후 서버가 돌려주는 데이터의 구조와 각 필드 의미를 정의한 규격입니다. 이걸 꼼꼼히 읽어두지 않으면 어떤 필드에서 체결 수량을 가져와야 하는지 헷갈리는 경우가 생깁니다. 제 경험상 이건 문서를 한 번 쭉 읽는 것보다, 테스트베드(Testbed)에서 직접 호출해 보면서 응답값을 눈으로 확인하는 게 훨씬 빠릅니다. 테스트베드란 실제 투자금 없이 API 호출을 시험해 볼 수 있는 공식 환경으로, 한국투자증권 오픈API 포털에서 바로 이용할 수 있습니다.

보안 리스크와 API 모니터링, 솔직한 생각

솔직히 이건 예상 밖이었습니다. 처음에는 “그냥 프로그램 돌려두면 끝이겠지” 싶었는데, 막상 운영해보니 생각지 못한 신경 쓸 거리가 두 가지 생기더라고요.

첫째는 보안 문제입니다. 웹 환경에서 주식 주문 API를 호출하는 구조다 보니, appkey와 appsecret 같은 보안코드가 노출될 경우 타인이 제 계좌로 임의 주문을 낼 수도 있습니다. 소액 투자라 실질적 피해가 크지 않더라도, 인증 정보 관리만큼은 타협하면 안 된다고 생각합니다. 환경변수로 분리하거나 별도 설정 파일에 보관하고 외부 접근을 차단하는 방식이 기본 중의 기본입니다. 금융 API 보안 관련 가이드라인은 한국인터넷진흥원(KISA) 보안 가이드에서도 확인할 수 있습니다.

둘째는 API 스펙 변경입니다. 실제로 한국투자증권 오픈API는 key 값이나 파라미터 구성이 조금씩 바뀌는 경우가 있습니다. 처음 세팅해두고 방치했다가 어느 날 주문이 안 들어가 있는 상황을 겪고 싶지 않다면, 공식 API 문서와 GitHub 샘플코드를 주기적으로 확인하는 습관이 필요합니다. 저도 주기적으로 엑셀 규격서를 받아두는데, 전체 API 문서가 엑셀 한 파일로 다운로드된다는 점은 솔직히 꽤 편리합니다. 변경사항 추적에 용이하거든요.

이런 번거로움에도 불구하고, 한 달 제한 없는 예약 매매와 나만의 매매 원칙을 코드로 구현할 수 있다는 점은 분명한 장점입니다. 일반 투자자가 직접 쓸 수 있는 오픈API 서비스를 제공해 준 부분은 정말 감사하다는 생각이 듭니다.

자주 묻는 질문

Q. 한국투자증권 오픈API 앱키(appkey) 발급은 어떻게 하나요?

A. 한국투자증권 오픈API 포털에 가입한 후 [서비스 신청] 메뉴에서 appkey와 appsecret을 발급받을 수 있습니다. 발급받은 보안코드로 REST API를 호출해 접근토큰(access_token)을 먼저 받아야 실제 주문이나 시세 조회가 가능합니다. 처음 발급 과정 자체는 어렵지 않으니 포털 가입 후 바로 진행해 보시면 됩니다.

Q. 모의투자와 실전투자 API 도메인이 다른가요?

A. 맞습니다. 모의투자는 https://openapivts.koreainvestment.com:29443, 실전투자는 https://openapi.koreainvestment.com:9443 으로 엔드포인트가 완전히 구분되어 있습니다. 처음 개발할 때 실수하기 쉬운 부분이라, 코드에 환경 변수로 분리해 두고 스위칭하는 방식을 추천합니다. 저도 초기에 모의투자 도메인으로 실전 주문을 날리려다 에러를 마주한 적이 있습니다.

Q. 부분 체결이 발생하면 자동매매 로직이 꼬이지 않나요?

A. 부분 체결 상황을 DB에서 체결 완료·미완료 상태와 실제 체결 수량으로 나눠서 기록하면 충분히 핸들링할 수 있습니다. 핵심은 주문 후 체결 내역 조회 API를 통해 실제 체결 수량을 확인하고, 미체결 잔량은 다음 사이클에서 처리 여부를 판단하도록 설계하는 것입니다. 처음에는 복잡해 보이지만, 컬럼 설계만 잘 해두면 로직 자체는 단순하게 유지할 수 있습니다.

Q. crond 말고 다른 스케줄링 방법도 있나요?

A. Ubuntu 환경 기준으로 crond가 가장 간단한 선택입니다. 다만 Python으로 개발한 경우라면 APScheduler 라이브러리를 쓰거나, 클라우드 환경이라면 AWS Lambda + EventBridge 같은 방식으로 서버리스 스케줄링을 구성하는 것도 가능합니다. 개인 서버가 있다면 crond가 설정도 간단하고 운영 부담이 적어서 소규모 자동매매에는 충분합니다.

Q. 한국투자증권 API 스펙이 자주 바뀌나요?

A. 큰 틀은 유지되지만 파라미터 이름이나 헤더 구성 등 세부 항목이 조금씩 변경되는 경우가 있습니다. 제 경험상 공식 포털의 엑셀 규격서를 가끔 내려받아 이전 버전과 비교해 보는 게 가장 확실한 방법이었습니다. GitHub의 공식 샘플코드도 업데이트가 반영되는 편이라 함께 모니터링하면 좋습니다.

자동매매 프로그램을 직접 만들어 운영해보면서 느낀 건, 기술 난이도보다 꾸준한 관리가 더 중요하다는 점이었습니다. API 스펙 모니터링, 보안코드 관리, 부분 체결 처리까지, 처음 세팅 이후에도 손이 조금씩 가는 건 사실입니다. 그래도 나만의 매매 원칙을 코드로 구현하고, 예약 기간 제한 없이 장기 운영이 가능하다는 것은 명확한 이점입니다. 소액 원칙 투자를 체계화하고 싶은 분이라면, 한번쯤 오픈API 포털을 직접 들여다보시길 권합니다. 이 글은 개인적인 경험과 의견을 공유한 것이며, 전문적인 금융 투자 조언이 아닙니다.

—
참고: https://apiportal.koreainvestment.com/apiservice-summary
https://www.kisa.or.kr/401/form?postSeq=010162

Similar Posts