핵심 요약
- 토스증권 오픈 API는 국내(KRX)·미국 주식의 시세 조회와 주문을 하나의 REST API로 처리하는 서비스로, 2026년 5월 사전 신청을 시작했습니다.
- 신청은 토스증권 WTS의 설정 > Open API 메뉴에서 client_id와 client_secret을 발급받으면 끝납니다.
- 챗GPT·클로드 같은 AI에 API 키를 연동하면 “내 포트폴리오 수익률 분석해줘” 같은 대화형 명령이 가능합니다.
- 주문 API는 초당 최대 6회(장 시작 직후 09:00~09:10은 초당 3회)로 제한되므로 자동매매 설계 시 반드시 고려해야 합니다.
토스증권 오픈 API는 토스증권 계좌만 있으면 누구나 신청할 수 있는 주식 자동매매·시세 조회용 REST API입니다. 국내 주식과 미국 주식을 하나의 통합 API로 다룰 수 있다는 점, 그리고 챗GPT·클로드 같은 AI 플랫폼과 바로 연동된다는 점이 기존 증권사 API와 가장 큰 차이입니다. 이 글에서는 신청 방법 3단계부터 제공 기능, AI 연동 활용법, 자동매매 시 주의해야 할 호출 제한까지 공식 개발자 문서 기준으로 정리했습니다.
토스증권 오픈 API란? 무엇이 가능한가
토스증권 오픈 API는 토스증권이 2026년 5월 사전 신청을 시작한 개인 투자자용 공개 API 서비스입니다. 표준 REST 방식으로 설계되어 파이썬, 자바스크립트 등 어떤 언어에서든 HTTP 요청만으로 연동할 수 있으며, 기준 서버 주소는 https://openapi.tossinvest.com입니다.
기존에 자동매매를 하려면 증권사별로 복잡한 OCX 설치나 별도 프로그램이 필요한 경우가 많았습니다. 토스증권 오픈 API는 웹 표준 기술만 사용하기 때문에 PC는 물론 클라우드 서버, 라즈베리파이 같은 소형 기기에서도 24시간 돌릴 수 있습니다. 특히 미국 주식 새벽 거래까지 API로 주문할 수 있어, 밤잠을 포기하지 않아도 분할 매수 전략을 자동으로 실행할 수 있다는 점이 직장인 투자자에게 가장 큰 매력입니다.
제공 기능 4가지 카테고리
공식 문서 기준으로 토스증권 오픈 API는 다음 네 가지 카테고리로 구성됩니다.
| 카테고리 | 주요 기능 | 대표 엔드포인트 | 필요 인증 |
|---|---|---|---|
| 인증 (Auth) | OAuth 2.0 액세스 토큰 발급 | POST /oauth2/token | client_id + secret |
| 시세·종목 정보 | 현재가·호가·체결·캔들 차트, 종목 정보, 환율, 장 운영 시간 | GET /api/v1/prices 등 | 토큰만 필요 |
| 계좌·자산 | 계좌 목록, 보유 주식·평가손익 조회 | GET /api/v1/holdings | 토큰 + 계좌 헤더 |
| 주문 | 주문 생성·정정·취소, 매수 가능 금액, 수수료 조회 | POST /api/v1/orders | 토큰 + 계좌 헤더 |
시세와 종목 정보는 계좌와 무관한 공개 데이터라 토큰만으로 호출할 수 있고, 내 계좌의 자산 조회나 주문 실행은 X-Tossinvest-Account라는 계좌 식별 헤더를 추가로 보내야 합니다. 캔들 차트는 1분봉과 일봉을 제공하므로 기술적 분석 기반 전략도 구현할 수 있습니다.
신청 방법 3단계 — 발급부터 첫 호출까지
1단계: 토스증권 WTS에서 클라이언트 등록
토스증권 WTS(웹 트레이딩 시스템)에 로그인한 뒤 설정 > Open API 메뉴로 들어가면 client_id와 client_secret을 발급받을 수 있습니다. 별도 심사 서류 없이 토스증권 계좌 보유 고객이라면 신청 가능합니다.
2단계: 액세스 토큰 발급
발급받은 키로 POST /oauth2/token을 호출해 OAuth 2.0 액세스 토큰을 받습니다. 방식은 Client Credentials Grant 하나로 통일되어 있어 인증 구조가 단순합니다.
curl -X POST 'https://openapi.tossinvest.com/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=발급받은_ID' \
-d 'client_secret=발급받은_SECRET'3단계: API 호출
받은 토큰을 Authorization: Bearer {토큰} 헤더에 담아 원하는 API를 호출하면 됩니다. 예를 들어 삼성전자(005930) 종목 정보는 GET /api/v1/stocks?symbols=005930 한 줄로 조회됩니다.
💡 팁: client_secret은 비밀번호와 같습니다. 깃허브 등 공개 저장소에 절대 올리지 말고, 환경변수나 별도 설정 파일로 분리해 관리하세요. 유출 시 타인이 내 계좌로 주문을 실행할 수 있습니다.
챗GPT·클로드 AI 연동 — 대화로 내 계좌 분석하기
토스증권 오픈 API의 가장 큰 차별점은 AI 플랫폼 연동입니다. 챗GPT나 클로드 같은 대형언어모델(LLM)에 발급받은 API 키를 연동하면, 코딩 없이도 “내 포트폴리오 수익률 분석해줘”, “A 종목 최근 3개월 일봉 보고 지지선·저항선 알려줘” 같은 대화형 명령으로 실시간 자산 평가와 시세 조회가 가능합니다.
활용 시나리오는 생각보다 다양합니다.
- 포트폴리오 리뷰: 보유 종목 조회 API와 연결해 AI가 섹터 편중, 손익 현황을 요약
- 매매 일지 자동화: 주문 내역 API를 읽어 AI가 일자별 매매 기록과 복기 노트 작성
- 조건 알림: 캔들·현재가 데이터를 주기적으로 조회해 설정한 조건 도달 시 알림
AI 자체가 처음이라면 클로드 사용법 총정리와 챗GPT 사용법 가이드를 먼저 읽고 오시면 연동 과정이 훨씬 수월합니다.
자동매매 전 반드시 알아야 할 호출 제한과 주의사항
자동매매 봇을 설계할 때 가장 먼저 확인해야 하는 것이 초당 호출 제한(Rate Limit)입니다. 공식 문서에 명시된 그룹별 한도는 다음과 같습니다.
| API 그룹 | 초당 요청 한도 | 비고 |
|---|---|---|
| 시세 (MARKET_DATA) | 최대 10회 | 캔들 차트는 별도 그룹, 초당 5회 |
| 주문 (ORDER) | 최대 6회 | 09:00~09:10에는 초당 3회로 축소 |
| 계좌 (ACCOUNT) | 최대 1회 | 가장 엄격한 제한 |
| 보유 자산 (ASSET) | 최대 5회 | 잔고 조회 |
| 인증 (AUTH) | 최대 5회 | 토큰은 캐싱해서 재사용 권장 |
한도를 초과하면 429 에러가 반환되며, 응답의 Retry-After 헤더에 적힌 시간만큼 대기 후 재시도하는 것이 공식 권장 사항입니다. 장 시작 직후 09시~09시 10분에는 주문 한도가 절반(초당 3회)으로 줄어들기 때문에, 시초가 매매 전략을 쓴다면 이 구간의 주문 큐 설계에 특히 신경 써야 합니다.
이 외에도 주문 금액이 1억 원 이상이면 confirmHighValueOrder 값을 true로 명시해야 주문이 접수되는 고액 주문 확인 장치가 있고, 실시간 트렌드 데이터는 베타 단계로 새벽 1시~6시에는 제한적으로 제공됩니다.
⚠️ 투자 유의: 자동매매는 코드 오류 하나가 곧바로 금전 손실로 이어질 수 있습니다. 반드시 소액·소량 주문으로 충분히 검증한 뒤 운용 규모를 늘리고, 손절 조건과 일일 최대 주문 횟수 같은 안전장치를 코드에 직접 넣어두세요. 금융투자상품은 원금 손실(0~100%)이 가능하며 그 손실은 투자자 본인에게 귀속됩니다.
기존 증권사 API와 무엇이 다른가
한국투자증권, 키움증권 등 기존 증권사들도 개인용 REST API를 제공하고 있습니다. 토스증권 오픈 API가 후발 주자임에도 주목받는 이유는 세 가지입니다.
- 국내+미국 통합 인터페이스: 시장별로 API 구조가 갈리지 않고 하나의 엔드포인트 체계로 KRX와 미국 주식을 모두 처리합니다.
- 발급 절차의 간편함: WTS 설정 메뉴에서 즉시 키를 발급받는 구조로, 별도 모의투자 승인 단계 없이 시작할 수 있습니다.
- AI 연동 지향 설계: 공식 문서 자체가 LLM이 읽기 좋은 형태(OpenAPI JSON 스펙)로 공개되어 있어, AI 코딩 도구로 봇을 만들 때 진입장벽이 낮습니다.
API로 미국 주식을 자동 매매하기 전에 기본 절차가 궁금하다면 미국주식 사는 방법 6단계를, 수익이 나기 시작했다면 해외주식 양도소득세 신고 방법과 해외주식 절세 전략도 함께 확인해 두는 것이 좋습니다.
결론 — 이런 분에게 추천합니다
- 미국 증시 시간대 때문에 새벽 매매를 포기했던 직장인 투자자
- 파이썬 기초만 알아도 분할 매수·리밸런싱을 자동화하고 싶은 분
- 챗GPT·클로드로 내 계좌를 대화하듯 분석하고 싶은 분
- 기존 증권사 API의 복잡한 발급 절차에 지쳤던 분
토스증권 오픈 API는 아직 사전 신청 단계의 신규 서비스인 만큼 엔드포인트와 한도가 변경될 수 있습니다. 실제 자동매매 코드를 작성하기 전에는 공식 개발자센터(developers.tossinvest.com)의 최신 문서를 반드시 확인하세요.
자주 묻는 질문 (FAQ)
토스증권 오픈 API는 누가 신청할 수 있나요?
토스증권 계좌를 보유한 고객이라면 신청할 수 있습니다. 토스증권 WTS에 로그인해 설정 > Open API 메뉴에서 client_id와 client_secret을 발급받으면 됩니다.
이용 요금이 따로 있나요?
API 이용 자체에 별도 요금은 공지되지 않았으며, 매매 시에는 일반 거래와 동일한 수수료 체계가 적용됩니다. 국내주식 매매수수료는 2026년 6월까지 무료이며 이후 KRX 체결 시 0.015%, NXT 체결 시 0.014%가 적용됩니다.
미국 주식도 자동매매가 가능한가요?
가능합니다. 주문 생성 API(POST /api/v1/orders)가 국내와 미국 주식을 모두 지원하며, 지정가·시장가 주문을 처리할 수 있습니다. 미국 장 운영 시간은 마켓 캘린더 API로 프리마켓·정규장·애프터마켓 정보를 조회할 수 있습니다.
웹소켓 실시간 시세도 제공되나요?
공식 문서 기준 현재는 REST API만 제공됩니다. 실시간성이 필요한 경우 현재가·체결 API를 허용 한도(시세 초당 10회) 내에서 주기적으로 호출하는 방식으로 구현해야 합니다.
API 키가 유출되면 어떻게 되나요?
client_secret이 유출되면 제3자가 내 계좌의 잔고 조회는 물론 주문까지 실행할 수 있습니다. 유출이 의심되면 즉시 WTS의 Open API 메뉴에서 키를 재발급하고, 코드에서는 키를 환경변수로 분리해 관리하는 것이 안전합니다.
코딩을 전혀 못해도 쓸 수 있나요?
AI 연동 기능을 활용하면 가능합니다. 챗GPT나 클로드에 API 키를 연동하면 코드 작성 없이 대화형 명령으로 포트폴리오 분석과 시세 조회를 할 수 있습니다. 다만 자동 주문까지 맡기는 것은 충분한 검증 후에 결정하는 것이 좋습니다.