토스증권 오픈 API: 국내·미국 시장 데이터와 거래를 코드로
목차
개요
토스증권 오픈 API는 국내(KRX) 및 미국 주식 시장의 데이터, 거래 기능, 계좌 관리에 접근할 수 있는 REST API다. 시세 데이터 조회부터 주문 생성과 포지션 추적까지, 증권 서비스의 핵심 기능을 코드로 다룰 수 있도록 설계되어 있다. 인증은 OAuth 2.0 Client Credentials Grant 방식을 사용한다.
배경
증권 데이터와 거래 기능을 프로그래밍 방식으로 다루려면 표준화된 인터페이스가 필요하다. 토스증권 오픈 API는 REST API 형태로 이러한 기능을 노출하여, 개발자가 국내와 미국 시장을 아우르는 애플리케이션을 구축할 수 있게 한다. 권위 있는 사양은 OpenAPI 3.0 JSON 문서로 제공되며, 개발자 문서와 인터랙티브 인터페이스도 함께 제공된다.
핵심 서비스
토스증권 오픈 API가 제공하는 핵심 서비스는 다음과 같다.
서비스 영역과 주요 기능
| 서비스 영역 | 주요 기능 |
|---|---|
| 시세 데이터(Market Data) | 실시간 호가창(orderbook), 가격 정보, 체결 내역, 가격 제한(상·하한), 캔들 차트 |
| 종목 정보(Stock Information) | 증권 마스터 데이터 및 투자자 유의 정보(경고) |
| 시장 인프라(Market Infrastructure) | 환율, 국내·미국 시장 캘린더 |
| 계좌 관리(Account Management) | 계좌 상세, 현재 보유 종목 |
| 거래 기능(Trading) | 주문 생성·정정·취소, 포지션 추적, 매수 가능 금액 계산, 수수료 상세 |
시세 데이터는 실시간 호가창과 가격 정보, 체결 내역, 가격 제한, 캔들 차트를 제공한다. 종목 정보는 증권 마스터 데이터와 함께 투자자 유의 정보를 다룬다. 시장 인프라는 환율과 국내·미국 시장 캘린더를 제공한다. 계좌 관리는 계좌 상세와 현재 보유 종목을 조회할 수 있다. 거래 기능은 주문 생성·정정·취소, 포지션 추적, 매수 가능 금액(buying power) 계산, 수수료 상세를 제공한다.
인증과 접근
모든 엔드포인트는 OAuth 2.0으로 발급한 액세스 토큰을 요구한다. 인증 방식은 OAuth 2.0 Client Credentials Grant이며, 발급받은 토큰은 표준 Bearer 토큰 형태로 요청에 사용한다. 계좌 관련 작업은 표준 Bearer 토큰 인증에 더해 X-Tossinvest-Account 헤더를 추가로 요구한다.
즉, 시세 데이터 조회와 같은 작업은 액세스 토큰만으로 충분하지만, 계좌 상세나 거래처럼 특정 계좌를 대상으로 하는 작업은 계좌 식별을 위한 헤더가 함께 필요하다.
핵심 리소스
개발에 필요한 핵심 리소스는 다음과 같다.
- Base 서버:
https://openapi.tossinvest.com - 권위 있는 사양: OpenAPI 3.0 JSON 문서
- 개발자 문서: 마크다운 API 레퍼런스와 브라우저 기반 인터랙티브 인터페이스 제공
또한 AI 에이전트와 비-JS 페처를 위한 /llms.txt 텍스트 포맷도 제공된다. 이를 통해 자바스크립트를 실행하지 못하는 클라이언트나 자동화 에이전트도 문서를 텍스트 형태로 읽을 수 있다.
개발자 활용
토스증권 오픈 API는 다양한 형태의 애플리케이션에 활용할 수 있다.
- 실시간 시장 모니터링
- 자동 매매 워크플로
- 포트폴리오 관리 시스템
- 국내·미국 거래소를 아우르는 멀티마켓 투자 애플리케이션 통합
시세 데이터로 실시간 시장을 모니터링하고, 거래 기능과 결합해 자동 매매 워크플로를 구성할 수 있다. 계좌 관리와 거래 기능을 활용하면 포트폴리오 관리 시스템을 구축할 수 있으며, 국내와 미국 시장을 함께 다루는 멀티마켓 투자 애플리케이션 통합도 가능하다.
의미와 시사점
토스증권 오픈 API는 국내(KRX)와 미국 시장을 하나의 인터페이스로 다룰 수 있게 한다는 점에서 의미가 있다. OAuth 2.0 표준 인증과 OpenAPI 3.0 사양 문서를 채택해, 표준 도구와 코드 생성 워크플로에 자연스럽게 통합할 수 있다. 특히 /llms.txt 포맷을 별도로 제공한다는 점은 AI 에이전트 기반 개발을 고려한 설계로 볼 수 있다. 시세 조회는 토큰만으로, 계좌·거래 작업은 계좌 헤더를 추가로 요구하는 구조는 권한 범위를 명확히 구분한다.
결론
토스증권 오픈 API는 시세 데이터, 종목 정보, 시장 인프라, 계좌 관리, 거래 기능을 REST API로 제공하는 종합 인터페이스다. OAuth 2.0 인증과 계좌 작업용 X-Tossinvest-Account 헤더 규칙을 이해하면, 국내와 미국 시장을 아우르는 시장 모니터링·자동 매매·포트폴리오 관리 애플리케이션을 코드로 구축할 수 있다. 자세한 내용은 개발자 문서를 참고하면 된다.