토스증권 OpenAPI가 드디어 오픈했어요

토스증권 OpenAPI가 드디어 오픈했어요

토스증권 OpenAPI가 드디어 오픈했어요. 저는 그동안 자동매매 시그널만 받고 주문은 손으로 넣었는데, 이걸 붙이고 나서는 종목 선정부터 주문까지 자동으로 실행되고 있어요. 쓰면서 좋았던 점과 아직 아쉬운 점을 정리해볼게요.

01. 문서를 Claude한테 그대로 던질 수 있어요

요즘 API 문서 사이트는 대부분 자바스크립트로 그려져서, AI 코딩 도구가 주소만 보고는 내용을 못 읽는 경우가 많아요. 그래서 보통 문서를 복사해서 붙여넣거나, 스크린샷을 찍어 넘기거나 했거든요.

 

토스증권 개발자 문서에는 llms.txt가 있어요. llms.txt는 사이트 문서를 LLM이 읽기 좋은 텍스트로 안내해주는 일종의 관례인데, 직접 열어보면 첫 줄부터 이렇게 자기소개를 해요.

토스증권 Open API 문서를 외부 LLM과 AI coding agent가 직접 읽기 위한 안내 파일입니다.

$ curl https://developers.tossinvest.com/llms.txt

# 인증 방식, base URL, 엔드포인트 카테고리가 텍스트로 내려와요
# openapi.json 이 source of truth 라고 명시되어 있어서
# Claude Code 에 이 주소만 주면 클라이언트 코드가 나와요

 

저는 Claude Code에 이 문서를 주고 파이썬 클라이언트를 만들었어요. 인증부터 시세 조회, 주문까지 파일 하나로 끝났고, 외부 패키지 없이 표준 라이브러리만으로 돌아가요. 만약 문서가 화면 캡처로만 읽히는 사이트였으면 이 과정이 복잡했을 거에요.

02. 키 2줄이면 주문까지 나가요

토스증권 Open API는 REST API로 별도 프로그램을 설치하거나 특정 운영체제를 요구하지 않아서, 저는 집에 있는 미니맥에서 파이썬으로 돌리고 있어요.

 

발급받는 것도 클라이언트 키 2개가 전부예요. 환경 파일에 두 줄 넣고 OAuth 토큰을 받으면 시세 조회부터 주문까지 다 돼요.

$ cat .env
TOSS_CLIENT_ID=tsck_live_...
TOSS_CLIENT_SECRET=tssk_live_...

# 준비물은 이 두 줄이 전부예요
# POST /oauth2/token 으로 토큰을 받으면
# 시세, 계좌, 주문이 같은 토큰으로 다 돼요

 

제공되는 API는 이렇게 묶여 있어요.

• 인증 (Auth) — OAuth2 토큰 발급
• 시세 (Market Data) — 현재가, 호가, 체결, 캔들, 상·하한가
• 종목 정보 (Stock Info) — 종목 기본 정보, 매수 유의사항
• 시장 정보 (Market Info) — 환율, 국내/미국 장 운영 캘린더
• 계좌·자산 (Account·Asset) — 계좌 목록, 보유 주식
• 주문 (Order) — 생성·정정·취소·조회, 매수 가능 금액, 매도 가능 수량, 수수료

시세 조회부터 주문, 그리고 주문 전에 확인할 매수 가능 금액과 매도 가능 수량까지, 자동매매에 필요한 건 다 있어요.

 

국내 주식과 미국 주식이 같은 API로 묶여 있는 것도 좋았어요. 문서 기준으로 키움 REST API는 아직 국내 주식 전용이고, 한국투자증권은 해외주식이 되지만 국내와 해외가 별도 카테고리로 나뉘어 있어요. 국내/해외 주문을 같은 엔드포인트 묶음 하나로 다루는 게 토스증권 OpenAPI 쪽 특징이에요.

 

그중에 저한테 가장 고마웠던 건 의외로 장 운영 캘린더 API였어요. 미국 공휴일, 반일장, 서머타임까지 캘린더에 다 반영되어 있어서, 제 코드에 박아놨던 장 시간 하드코딩을 전부 지웠어요!

03. 에러가 다음 행동을 알려줘요

개발자 분들은 다 아시겠지만 프로그램을 돌릴 때 에러 메시지는 친절할수록 좋더라구요.

 

그동안 증권사 API는 에러 코드표 대조가 일이었다고 해요. 키움 OpenAPI는 -308 같은 음수 코드가 떨어지고 무슨 뜻인지는 개발가이드 코드표에서 찾아야하고, 한국투자증권은 메시지가 같이 오지만 코드가 EGW00201 같은 약어라 결국 문서의 에러코드 페이지를 찾게 되고요. 하지만 토스증권은 개발자 친화적 에러 코드와 한국어 에러 메시지 및 해결 힌트까지 함께 내려와요.

{
  "error": {
    "requestId": "01HXYZABCDEFG123456789",
    "code": "invalid-request",
    "message": "주문 방향이 올바르지 않습니다.",
    "data": {
      "field": "side",
      "allowedValues": ["BUY", "SELL"]
    }
  }
}

 

주문 가능 금액이 부족하면 insufficient-buying-power, 주문 시간이 아니면 order-hours-closed 식이라 코드표 없이 로그만 봐도 어떤 이슈인지 파악이 가능해요. 추가로 data 필드의 allowedValues처럼 고치는 방법까지 알려주니 너무 편했어요.

 

HTTP/1.1 429 Too Many Requests
  retry-after: 1
  x-ratelimit-limit: 10
  x-ratelimit-remaining: 0
  x-ratelimit-reset: 1

  {
    "error": {
      "code": "rate-limit-exceeded",
      "message": "Rate limit 초당 요청 수를 초과했습니다."
    }
  }

호출이 한도에 걸리면 429와 함께 Retry-After 헤더로 얼마나 대기해야할 지 알려주고 있어요.

 

그리고 주문 생성에는 멱등키를 같이 보낼 수 있어요. 네트워크가 끊겨서 재시도해도 같은 키면 중복 주문이 안 나가고, 이미 처리 중이면 처리 중이라고 에러로 알려줘요. 무인으로 돈이 나가는 시스템에서는 이게 제일 고마운 설계였어요.

04. 아쉬운 점...

현재 REST만 제공하고 아쉽게도 WebSocket 실시간 시세는 지원하지 않아요. 그래서 저는 보유 종목 가격을 1초에 한 번 폴링해서 손절·익절을 처리하고 있어요. 다행히 시세 API가 여러 종목을 한 번에 받아줘서 보유 종목 전체를 호출 한 번으로 처리할 수 있었어요.

 

모의투자나 샌드박스도 아직 없어요. 그래서 저는 클로드 코드를 통해 백테스팅 및 모의 투자를 돌리는 방식으로 대체하고 있어요.

 

이제 막 나온 서비스라 웹소켓 기능이 빠르게 추가되길 기대하고 있어요. ( 모의투자가 없는 건, 요즘은 mock을 Claude가 다 짜줘서 생각보다 아쉽지 않더라구요. )

 

참고로 지금은 아직 사전 신청 단계라, 신청하면 순차적으로 사용할 수 있게 열어주고 있는 것으로 보여요. 토스증권 계좌가 있으면 PC 웹에서 신청할 수 있어요.

 

지금도 미국 장이 열리는 밤이면 이 API로 주문이 나가요. 시세 폴링부터 체결 기록까지 사람 손 없이 도는 게 며칠째인데, 아직은 별 탈 없이 잘 돌고 있어요.

 

문서: 토스증권 Open API 가이드