한국에서 미국주식 자동매매, 어떤 증권사 API로 시작할까 — KIS vs 토스증권

한국에서 미국주식 자동매매, 어떤 증권사 API로 시작할까 — KIS vs 토스증권

자동매매 · 증권사 Open API · KIS · 토스증권 · OAuth 2.0

한국에 살면서 미국 주식을 코드로 자동매매하려면 가장 먼저 넘어야 할 관문이 증권사 API다. 필자는 한국투자증권(KIS) Open API로 멀티 버킷 미국주식 자동매매 봇(이하 미장봇)을 직접 만들어 운영하고 있다. 그런데 2026년, 토스증권이 REST API를 공개하면서 KIS가 더 이상 유일한 선택지가 아니게 됐다. 이 글은 실제로 KIS로 봇을 만든 1차 경험과, 새로 등장한 토스증권 Open API를 나란히 놓고 “무엇으로 시작할지”를 결정하는 기준까지 정리한다.

1. 왜 증권사 API가 자동매매의 출발점인가

자동매매 봇이 하는 일은 결국 세 가지로 압축된다 — 시세를 읽고, 잔고를 확인하고, 주문을 낸다. 이 셋을 사람 손 없이 프로그램이 하려면 증권사 서버와 직접 대화할 통로가 필요하다. 그 통로가 바로 Open API다.

과거의 증권사 자동화는 대부분 HTS(홈트레이딩시스템)를 상시 켜둔 채 윈도우 전용 COM/OCX 인터페이스에 붙는 방식이었다. PC를 끄면 봇도 죽고, 윈도우가 아니면 돌릴 수도 없었다. 반면 REST API는 별도 프로그램 설치 없이 웹 표준 HTTP 요청만으로 증권사 서버와 데이터를 주고받는다. 리눅스 서버, 클라우드, 라즈베리파이 어디서든 24시간 돌릴 수 있다는 뜻이다. 미국 장은 한국 시간으로 밤~새벽에 열리므로, “꺼지지 않는 서버에서 돌릴 수 있다”는 점은 미국주식 자동매매에서 특히 중요하다.

2. 인증의 심장 — OAuth 2.0 토큰

KIS든 토스든, 첫 단추는 OAuth 2.0 토큰 발급이다. 발급받은 앱 키(AppKey)와 시크릿(Secret)을 증권사에 보내 액세스 토큰을 받고, 이후 모든 API 요청 헤더에 그 토큰을 실어 보낸다. 두 증권사가 쓰는 방식이 사실상 동일한 client_credentials 그랜트라, 한쪽 인증을 이해하면 다른 쪽도 그대로 통한다.

▲ 토큰은 매번 새로 받는 게 아니라, 캐시해 두고 만료 직전까지 재사용한다. 발급 호출 자체에 빈도 제한이 걸려 있기 때문이다.

토큰을 받는 요청은 이렇게 생겼다. KIS의 경우 엔드포인트가 /oauth2/tokenP다.

curl -s -X POST "https://openapi.koreainvestment.com:9443/oauth2/tokenP" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "appkey":    "'"$KIS_APP_KEY"'",
    "appsecret": "'"$KIS_APP_SECRET"'"
  }'
# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":86400}

받은 토큰은 매 요청 헤더에 실린다. KIS는 토큰뿐 아니라 appkey·appsecret까지 헤더에 함께 요구한다(이 부분이 토스와 다르다).

@property
def headers(self) -> dict:
    return {
        "content-type": "application/json; charset=utf-8",
        "authorization": f"Bearer {self.token}",
        "appkey":    self.app_key,      # KIS는 헤더에도 키가 필요
        "appsecret": self.app_secret,
    }

그래서 토큰은 받자마자 파일에 저장하고, 만료 직전까지 그대로 재사용한다. 미장봇은 이렇게 캐시한다 — 시크릿이 담기므로 파일 권한을 0600으로 잠그고, 실전/모의 환경이 섞이지 않게 캐시에 is_virtual 플래그를 함께 저장해 환경이 다르면 캐시를 버린다.

def _save_cached_token(self):
    with open(TOKEN_FILE, "w") as f:
        json.dump({
            "token":      self._token,
            "expires":    self._token_expires,
            "is_virtual": self.is_virtual,   # 실전/모의 구분
        }, f)
    os.chmod(TOKEN_FILE, 0o600)              # 소유자만 읽기

def _load_cached_token(self):
    data = json.load(open(TOKEN_FILE))
    if data.get("is_virtual") != self.is_virtual:
        return None       # 환경(실전↔모의) 불일치 → 캐시 폐기
    return data           # 만료 60초 전까지 재사용

3. 운영 환경 — 키는 어디에 두고 어떻게 지키나

API 키와 시크릿은 코드에 하드코딩하면 안 된다. 깃에 한 번 올라가면 사실상 영구히 노출된다. 미장봇은 모든 비밀값을 프로젝트 루트의 .env 파일에 두고, 이 파일을 단일 진실 소스(single source of truth)로 삼는다. .gitignore에 반드시 넣어 커밋을 원천 차단한다.

KIS_APP_KEY=PSxxxxxxxxxxxxxxxxxxxxxxxx
KIS_APP_SECRET=xxxxxxxx...base64...padding==
KIS_ACCOUNT_NO=12345678-01
TRADING_MODE=paper        # 처음엔 모의로
TEST_MODE=on              # 1주 고정 검증 모드

여기서 의외로 자주 데이는 지점이 하나 있다. 시크릿이 base64라 =로 끝나는 경우, 셸 스크립트로 .env를 파싱하다 마지막 1바이트가 잘려 나갈 수 있다. 그러면 키·헤더·토큰이 전부 정상으로 보이는데도 인증만 실패한다(증상은 HTTP 500). 그래서 셋업 직후, 셸이 읽은 시크릿 길이와 파일 원본 길이를 한 번 맞춰보는 습관이 시간을 아낀다.

# 셸이 export한 길이 vs .env 파일 원본 길이 — 다르면 파싱이 1바이트 먹은 것
echo "exported = ${#KIS_APP_SECRET}"
grep '^KIS_APP_SECRET=' .env | sed 's/^KIS_APP_SECRET=//' | tr -d '\n' | wc -c

로그를 남길 때도 주의가 필요하다. 디버깅하다 키·시크릿·토큰을 그대로 찍으면 그 로그 파일이 곧 유출 경로가 된다. 미장봇은 비밀값을 앞 4자리만 남기고 마스킹해서 찍는다. “이 사고는 왜 일어나는가”를 다루는 자세한 진단은 이 시리즈의 에러 편에서 따로 정리한다.

4. KIS Open API — 미장봇이 실제로 쓴 길

미장봇은 한국투자증권 Open API 위에 올렸다. 실제 운영하며 정착시킨 토큰 관리 패턴은 다음 세 가지다.

① 토큰 캐시 — 파일에 저장하고 23시간 재사용. KIS 토큰의 유효기간은 약 24시간이다. 미장봇은 받은 토큰을 config/token.json에 저장하고, 만료 60초 전까지는 그대로 재사용한다. 시크릿이 담기므로 파일 권한은 0600(소유자만 읽기)으로 잠근다.

② 실패 시 지수 백오프 — 락아웃을 스스로 피한다. 토큰 발급이 실패하면 곧바로 재시도하지 않고 단계적으로 대기 시간을 늘린다. 미장봇의 실제 스케줄은 다음과 같다.

# 토큰 발급은 분당 1회 제한. 실패가 누적되면 다중 시간 락아웃으로 번진다.
# 그래서 실패 시마다 다음 재시도까지 대기를 키운다.
_BACKOFF_SCHEDULE = (60, 300, 900, 1800, 3600)   # 1분 → 5분 → 15분 → 30분 → 1시간

# 유효한 캐시 토큰도 없고 백오프 중이면, 빈 문자열을 돌려주고
# CRITICAL 로그를 남긴다 — 수많은 401 대신 '근본 원인'이 한 줄로 보이도록.

③ 모의투자(paper) 분기. KIS는 실전 계좌와 별개로 모의투자 서버를 제공한다. 베이스 URL에 openapivts가 들어가면 모의 환경으로 인식한다. 돈을 걸기 전에 주문 로직 전체를 안전하게 검증할 수 있다는 점이 KIS의 큰 강점이다.

④ Cold-start 워밍업 — 새 프로세스의 첫 1분을 견딘다. 봇을 갓 띄운 직후 첫 15~60초 동안 KIS가 대부분의 GET API에 HTTP 500 + 빈 body를 돌려주는 구간이 있다(서버 측 세션 priming 지연). 하필 이 구간에 자본 동기화(_sync_capital)가 걸리면 capital=0이 되고, 그날 주문 수량이 int(capital/price)=0으로 굳어 매매가 통째로 막힌다. 내부의 1·2·4초 짧은 재시도로는 이 구간을 못 뚫어서, 미장봇은 가벼운 시세 엔드포인트를 10초 간격으로 최대 90초 폴링하는 워밍업을 초기화 직후에 끼웠다.

def warm_up(self, max_secs=90, poll_interval=10) -> bool:
    # 가벼운 quote 엔드포인트를 retry 없이 10초 간격으로 폴링,
    # 200이 오면 즉시 종료. KIS 세션이 데워질 때까지 기다린다.
    # 실패해도 봇은 진행 — 다른 호출은 각자 재시도 경로가 있으니까.
    url = f"{self.base_url}/uapi/overseas-price/v1/quotations/price"
    ...  # 200 받으면 True, 타임아웃이면 False

KIS의 또 하나의 특징은 비슷하게 생긴 API가 용도별로 갈린다는 점이다. 특히 잔고/주문가능금액 계열이 헷갈리기 쉽다. 미장봇이 정리한 매핑은 다음과 같다(이 구분을 놓치면 HTTP 500이 난다).

5. 토스증권 Open API — 2026년에 열린 새 선택지

2026년 5월경, 토스증권이 Open API를 공개했다. “새벽 자동매매·AI 계좌분석”을 전면에 내세웠고, 챗봇(LLM)에 자기 API 키를 연동해 대화형으로 포트폴리오를 분석하는 활용까지 홍보했다. 핵심은 국내(KRX)와 미국 주식을 하나의 인터페이스로 묶은 통합 REST라는 점이다.

인증은 KIS와 마찬가지로 OAuth 2.0 client_credentials이고, 엔드포인트는 /oauth2/token으로 액세스 토큰을 받는다(만료 약 1시간). 제공 기능은 크게 6개 범주로 나뉜다.

신청 방법은 간단하다. 토스증권 계좌가 있어야 하고, 토스 앱에서 더보기 → Open API → 신청 경로로 들어가 Client ID/Secret을 발급받는다. 매매 수수료는 기존 토스증권 계좌 요율과 동일하며 API 사용에 별도 추가 수수료는 없다(국내 주식 수수료는 2026년 6월까지 면제 프로모션이 있었다).

토스가 마케팅에서 특히 강조한 활용처는 LLM 연동이다. 챗봇(ChatGPT·Claude 등)에 발급받은 API 키를 물려, “내 포트폴리오 수익률을 분석해줘” 같은 대화형 명령으로 실시간 자산 평가·시세 조회를 시키는 그림이다. 자동매매와 직접 관계는 없지만, “REST API + OpenAPI 스펙”이라는 표준 구조 덕분에 외부 도구와 엮기 쉽다는 점은 토스의 분명한 강점이다. 통합 환율(/exchange-rate)과 양 시장 캘린더(/market-calendar)를 한 API에서 주는 것도, 국내·미국을 함께 굴리는 봇에는 실용적이다.

6. KIS vs 토스증권 — 정면 비교

두 API를 자동매매 관점에서 항목별로 비교하면 다음과 같다. 인증 구조가 거의 같다는 점, 그리고 “검증 환경(모의투자)”과 “실시간 수단(WebSocket)”에서 갈린다는 점이 핵심이다.

※ 토스 항목은 발행 시점의 3rd-party 가이드·뉴스 기준이다. 모의투자·WebSocket 지원 여부는 추후 추가될 수 있으니 도입 전 공식 문서로 재확인할 것.

7. 그래서 무엇으로 시작할까 — 의사결정

정답은 “용도에 따라 다르다”이지만, 막연하지 않게 세 갈래로 정리할 수 있다. 아래 흐름도를 따라가면 자기 상황에 맞는 선택이 나온다.

▲ 검증 환경(모의투자)과 실시간 수단(WebSocket)이 첫 분기점이다.

미장봇은 모의투자로 주문 로직을 먼저 검증해야 했기에 KIS를 골랐다. 만약 지금 처음부터 다시 시작한다면, 저빈도 멀티 버킷 전략(분·일 단위 리밸런스)에는 토스증권의 통합 REST도 충분히 현실적인 후보다. 두 API의 인증·요청 구조가 거의 같아, 한쪽으로 만든 봇을 다른 쪽으로 옮기는 비용도 생각보다 작다.

8. 시작 전에 알아둘 함정 (다음 글 예고)

어느 API를 고르든, 인증을 붙이는 순간 거의 반드시 만나는 에러들이 있다. 미장봇을 운영하며 실제로 겪고 정리한 대표적인 함정 몇 가지를 미리 귀띔한다 — 자세한 진단·해결은 이 시리즈의 뒤 글에서 다룬다.

이 세 가지는 모두 “증상은 서버 탓처럼 보이는데 원인은 내 쪽”인 경우다. API 연동의 가장 큰 시간 낭비가 여기서 나온다.

9. 정리

다음 글에서는 이 API 위에 시세·잔고·주문을 호출하는 기본 연계 함수를 어떻게 감싸는지, 실제 코드로 이어간다.

※ 이 글은 특정 증권사·상품에 대한 투자 권유가 아니라, 자동매매 시스템을 직접 만들며 정리한 엔지니어링 기록이다. API 스펙·수수료·정책은 각 증권사 공식 문서를 기준으로 하며, 시점에 따라 달라질 수 있다.