키움이 해외주식 REST API를 열었다 — 파이썬 자동매매 전체 그림

자동매매를 만들 때 가장 큰 벽은 "증권사에 어떻게 주문을 넣느냐" 다.

국내 해외주식은 오랫동안 공식 API가 없었다. 그래서 예전엔 프로그램이 HTS(영웅문Global) 창을 직접 클릭하게 만들어야 했다 — 불안정하고, 32비트·관리자 권한 같은 제약도 많았다. 그런데 이제 키움이 해외주식 REST API를 공식 제공한다. 공식 통로가 열린 것이다. 이 강좌는 그 REST API로 자동매매를 처음부터 만든다. (GUI 자동화는 이제 필요 없다.)

이 강좌를 위한 준비 (선수지식·도착점)

선수지식: 파이썬 기초(함수·클래스·dict)면 충분하다. 웹/프레임워크 지식은 필요 없다.
필요한 것: 키움증권 계좌(해외주식) + 키움 REST API 키. (2편에서 발급)
도착점: 이 강좌를 끝내면 모의계좌에 자동으로 주문이 나가고, 규칙(그리드)대로 사고팔며, 체결을 텔레그램으로 받는 기본 시스템을 직접 만들 수 있다.
소스 코드: 각 편에 복붙하면 돌아가는 실제 코드를 넣는다. 여기서 만드는 건 '작동하는 기본형'이고, 안정화·GUI·백테스트까지 통합한 완성 시스템은 별도로 이어진다.

무엇을 만드나 — "예약해두면 알아서"

우리가 만들 v1의 컨셉은 Set-and-Forget(설정하고 잊기) 이다.

종목·가격·수량을 설정해두면
REST API로 영웅문에 지정가 주문을 한 번 제출한다
이후는 키움의 체결(매칭) 엔진이 가격이 도달하면 알아서 체결한다
우리 프로그램은 체결 내역만 주기적으로 조회해서, 체결되면 텔레그램으로 알림을 보낸다

왜 이 방식이 영리한가

현재가를 쉼 없이 감시할 필요가 없다. 주문을 한 번 제출해두면 매칭은 증권사가 한다.
프로그램이 꺼져도 주문은 살아 있다. 이미 제출된 지정가 주문은 키움 서버에 남아 있다.
REST라서 가볍다. 브라우저·GUI·32비트 같은 제약이 사라졌다. 파이썬 표준 라이브러리(urllib)만으로 호출할 수 있어 외부 의존성이 없다.

전체 그림 (한 장)

KiwoomRestClient      ← 토큰 발급 + TR(거래) 호출 (표준 urllib)
   └ KiwoomRestController  ← 현재가·잔고·주문·체결을 앱의 언어로 감쌈
        └ GridManager / TradingWorker  ← 매매 규칙 + 자동 루프
             ├ SQLite         ← 주문·포지션 상태 저장 (재시작해도 복원)
             ├ TelegramNotifier ← 체결·오류 알림
             └ Dashboard      ← 현황을 웹으로 퍼블리시 (선택)

KiwoomRestClient — OAuth 토큰을 받고, 미국주식 시세·잔고·주문·체결 TR을 호출한다. 강좌의 심장.
KiwoomRestController — TR 응답(키움 특유의 필드명)을 앱이 쓰기 좋은 형태로 감싼다.
GridManager / TradingWorker — 규칙(그리드 등)에 따라 언제 사고팔지 정하고, 주기적으로 돌린다.
SQLite / Telegram / Dashboard — 상태 저장, 알림, 현황 공개.

설계 포인트: 컨트롤러가 "GUI를 클릭"하든 "REST를 호출"하든, 위쪽 매매 로직은 한 줄도 바뀌지 않게 인터페이스(seam)를 맞췄다. 그래서 GUI 버전에서 REST 버전으로 심장만 갈아끼울 수 있었다. 좋은 설계의 힘이다.

핵심 기술 스택

기술	역할
Python (표준 `urllib`)	의존성 없이 REST 호출 (32비트 불필요)
키움 REST API	토큰(OAuth2) + 미국주식 시세/잔고/주문/체결
SQLite	주문·포지션 상태를 로컬 DB에 저장
pandas_market_calendars	미국 장 휴장일·조기폐장 조회
PyQt5 (선택)	주문 관리·상태·로그 데스크톱 GUI

이 강좌에서 만들 것 (7편)

왜 만드나 + 전체 그림 ← 지금 이 글
개발 환경 + 키움 REST API 키 발급
인증(토큰) + 첫 TR 호출 — OAuth2, 캐싱, rate limit, 실전 함정
시세·잔고·체결 조회 — 미국주식 현재가·잔고·체결내역
주문 실행 — 매수/매도/취소, 그리고 가격 포맷의 함정
규칙 기반 매매 로직 (그리드) — tier 포인터로 사고팔기
안전장치·운영·알림 — 드라이런·수량 대조·드로다운 알림·텔레그램

⚠️ 시작 전에 꼭 읽어주세요

투자 위험: 자동매매는 원금 손실 위험이 있습니다. 이 강좌는 기술(프로그래밍) 교육이며, 투자 권유나 특정 종목·시점 추천이 아닙니다. 수익을 보장하지 않습니다. 잃어도 되는 여윳돈으로만 검토하세요.
약관·규정: 증권사 API 이용약관과 자동매매 관련 규정을 진행 전 반드시 확인하세요.
반드시 소액·모의부터: 키움은 모의 도메인(mockapi)을 제공합니다. 모의와 소액으로 충분히 검증한 뒤에만 실전에 쓰세요.

다음 편 예고

2편에서는 개발 환경을 세팅하고 키움 REST API 키(appkey/secretkey)를 발급받습니다. 여기서부터는 GUI도, 32비트도 필요 없어요 — 그냥 파이썬과 인터넷만 있으면 됩니다.

이 강좌는 자동매매의 기초를 직접 손으로 만드는 여정입니다. 질문은 이 글 아래 댓글로 편하게 남겨주세요 — 함께 만들어가요.