키움 OpenAPI+(OCX)에서 REST API로 전환하기 — 뭐가 풀리고 뭐가 달라지나

OCX로 잘 돌아가던 코드, 굳이 REST로 옮겨야 하나

키움증권 자동매매를 처음 짤 때 OpenAPI+(OCX 기반)로 시작한 사람이 많다. 오랫동안 국내 개인 개발자 사이에서 사실상 표준처럼 쓰여왔고, 관련 자료도 많다. 그런데 키움증권 REST API로 넘어가려고 문서를 펼치면, "이걸 굳이 왜 갈아타야 하나"라는 질문부터 든다. 이 글은 그 질문에 답하기 위해, 두 방식의 개념적인 차이와 전환할 때 실제로 달라지는 지점을 정리한다.

이 글의 범위

OpenAPI+(OCX)의 정확한 버전별 스펙이나 최신 지원 현황을 단정하지 않는다. "윈도우 환경에서 동작한다", "증권사 프로그램 설치가 전제된다" 같은 일반적으로 알려진 수준만 다루고, 정확한 사양은 항상 키움증권 공식 문서를 기준으로 확인해야 한다. 실제 화면·코드·전환 스크립트도 담지 않는다.

기존 OpenAPI+(OCX)는 어떤 제약을 안고 있었나

OpenAPI+는 OCX(ActiveX 계열) 컨트롤을 프로그램에 심어서 쓰는 방식으로 알려져 있다. 이 방식은 몇 가지 특징을 공통적으로 따라다닌다.

윈도우 환경 전제. OCX 컨트롤 자체가 윈도우 플랫폼에 종속적인 기술이라, 리눅스나 맥에서 곧바로 쓰기는 어렵다고 알려져 있다.
증권사 프로그램 설치가 선행 조건인 경우가 많다. 로그인이나 인증 과정에서 별도 프로그램(HTS 등)이 함께 필요한 구조로 알려져 있다.
그래서 상시 운영에 제약이 따른다. 24시간 무인으로 돌리려면 결국 윈도우 PC나 윈도우 서버를 켜둬야 하는 방식이 일반적이다.

다만 이건 어디까지나 널리 알려진 수준의 특징이다. 실제 최신 버전에서 무엇이 되고 안 되는지는 시기마다 달라질 수 있어, 이 글에서 단정하지 않는다.

REST API로 옮기면 무엇이 풀리는가

REST API는 그냥 HTTP 요청이다. 이 단순한 사실 하나가 위에서 나열한 제약을 대부분 풀어준다.

OS 독립적이다. HTTP 요청을 보낼 수 있는 환경이면 리눅스든 맥이든 상관없다.
언어 독립적이다. OCX처럼 특정 컨트롤을 지원하는 언어·환경에 묶이지 않고, HTTP 클라이언트가 있는 언어라면 대부분 연동할 수 있다.
서버 배포가 가능해진다. 상시 켜진 윈도우 PC가 아니라, 클라우드 서버 같은 환경에 자동매매 코드를 올려 무인으로 돌릴 수 있는 길이 열린다. 이게 REST 전환을 고려하는 가장 실질적인 이유인 경우가 많다.

정리하면, OCX가 "특정 플랫폼에 설치된 프로그램"에 의존하는 방식이었다면, REST는 "네트워크로 요청을 주고받는" 방식으로 전제 자체가 바뀐다.

옮길 때 개념적으로 달라지는 것 두 가지

전환은 단순히 "같은 기능을 다른 창구로 부르는" 정도가 아니다. 코드를 짜는 사고방식 자체가 바뀌는 지점이 두 군데 있다.

첫째, 인증 방식이 다르다. OCX 방식은 로그인 과정 자체가 프로그램 레벨의 인증(로그인 창, 공동인증서 절차 등)에 가깝다고 알려져 있다. 반면 REST API는 App Key/Secret으로 접근 토큰을 발급받아 관리하는 방식이다. 로그인을 한 번 해두고 세션이 유지되는 게 아니라, 토큰의 발급·만료·갱신을 코드가 직접 챙겨야 한다는 뜻이다.

둘째, 요청·응답 방식이 다르다. OCX는 함수를 호출한 뒤 결과를 이벤트(콜백)로 돌려받는 비동기 구조가 흔하다고 알려져 있다. 반면 REST는 요청을 보내고 그 자리에서 응답을 받는 동기적인 호출-응답 구조가 기본이다. 의사코드로 대비해보면 이런 느낌이다.

코드 보기

# OCX류 - 이벤트 콜백 방식(개념 예시)
call_balance_request()
on_receive_balance_event(data):
    handle(data)

# REST - 요청-응답 방식(개념 예시)
response = http_post(balance_endpoint, headers=auth_headers)
handle(response.json())

여기서 중요한 건, 이게 단순 문법 차이가 아니라는 점이다. 콜백 기반으로 짜여 있던 상태 관리·에러 처리 로직을 통째로 요청-응답 구조에 맞게 다시 설계해야 한다. "함수 이름만 바꾸면 되겠지"라고 가볍게 보면 전환 작업량을 과소평가하기 쉽다.

함정 — 기능이 100% 같다고 가정하면 안 된다

전환을 준비하면서 가장 위험한 가정은 "OCX에서 되던 건 REST에서도 당연히 다 되겠지"다. 이건 검증 없이 성립한다고 믿으면 안 되는 전제다.

이전에 키움 미국주식 API를 조사하다가 겪은 일이 정확히 이 함정과 관련이 있다. 당시 AI에게 조사를 맡겼더니 "미국주식 잔고 조회는 지원하지 않는다"는 결론을 내놓았는데, 근거로 삼은 소스가 최신이 아니었다. 실제로는 얼마 전 REST API 쪽에 미국주식 기능이 새로 열려 있었다. 그럴듯한 근거가 있는 답이라도, 결정적인 사실은 1차 원본(공식 문서·포털)에서 다시 확인해야 한다는 교훈이었다.

OpenAPI+와 REST API의 관계도 마찬가지로 접근해야 한다. 어느 한쪽에만 있는 기능이 있을 수도 있고, 이름은 비슷해도 응답 형식이나 세부 조건이 다를 수도 있다. 이걸 목록으로 단정해서 나열하는 건 이 글의 역할이 아니다 — 시기에 따라 계속 바뀔 수 있는 내용이기 때문이다. 실제로 전환한다면 지금 쓰고 있는 기능을 하나씩 목록으로 만들어, REST 쪽 공식 문서에서 대응하는 항목이 정말 있는지 하나하나 대조하는 절차가 필요하다. "안 써봤지만 되겠지"로 넘어가는 순간, 실전에서 갑자기 막히는 기능을 만날 위험을 떠안는 셈이다.

언제는 굳이 REST로 안 옮겨도 되는가

전환이 항상 정답은 아니다. 균형 잡힌 시각에서 보면, 다음과 같은 경우엔 무리해서 옮길 이유가 크지 않다.

이미 OCX 기반으로 안정적으로 돌아가고 있고, 문제를 겪은 적이 없는 경우. 잘 도는 시스템을 굳이 흔들 이유는 없다.
상시 켜진 윈도우 환경(PC 또는 서버)을 유지하는 데 실질적인 부담이 없는 경우. 서버 독립성이 절실한 상황이 아니라면 전환의 이득이 작다.
전환 자체가 공짜가 아니라는 점. 인증 로직 재작성, 요청-응답 구조 재설계, 기능 대조 검증까지 전부 새로 드는 작업이다. "REST가 더 최신이니 무조건 낫다"는 성급한 결론은 피하는 게 맞다.

반대로 서버 배포·다른 언어 환경·다중 OS 운영처럼 REST가 풀어주는 제약이 실제로 발목을 잡고 있다면, 그때가 전환을 검토할 시점이다.

오늘의 정리

OpenAPI+(OCX)는 윈도우 환경과 증권사 프로그램 설치를 전제로 한다고 알려져 있고, REST API는 이 제약에서 벗어나 OS·언어에 독립적으로 서버 배포까지 가능해진다.
전환하면 인증 방식(App Key/Secret 기반 토큰)과 요청·응답 방식(콜백 → 동기 호출-응답)이 개념적으로 바뀌어, 기존 로직을 다시 설계해야 한다.
두 방식의 기능이 100% 동일하다고 가정하면 안 된다. "그럴듯한 근거도 최신이 아닐 수 있다"는 교훈처럼, 지금 쓰는 기능을 하나씩 공식 문서로 대조 검증해야 한다.
이미 OCX로 안정적으로 운영 중이고 서버 독립성이 필요 없다면, 굳이 지금 옮길 이유는 없다.
전환 판단은 "더 최신이라서"가 아니라 "지금 겪고 있는 제약을 실제로 풀어주는가"를 기준으로 해야 한다.

이 글은 키움증권 API 전환에 관한 일반적인 개념을 정리한 것이며, 정확한 기능 차이와 최신 사양은 반드시 공식 개발자 문서에서 확인해야 합니다. 투자 조언이 아니고 특정 종목이나 매매기법을 추천하지 않습니다. 수익 보장은 없으며, 투자 손실의 책임은 투자자 본인에게 있습니다.