질문
공주님이 토스증권 Open API로 어디까지 사용할 수 있는지 확인을 요청했다. 확인 기준은 공식 랜딩 페이지, 개발자용 llms.txt, overview 문서, OpenAPI JSON 1.0.3이다.
한줄 결론
토스증권 Open API는 개인 본인 계좌 기준으로 국내·미국 주식의 시세 조회, 보유자산/포트폴리오 조회, 주문 생성·정정·취소까지 가능하다. 즉 개인용 투자 대시보드, 포트폴리오 분석, 알림, 제한적 자동매매 봇까지는 만들 수 있지만, 입출금·환전·상업적 외부 서비스 배포·실시간 웹소켓 스트리밍은 현재 범위 밖이다.
가능한 기능
인증·접근
- OAuth 2.0 Client Credentials Grant로 access token을 발급한다.
- 모든 API는
Authorization: Bearer ***헤더가 필요하다. - 계좌·자산·주문 API는 추가로
X-Tossinvest-Account헤더가 필요하다. - API Key는 사전 신청 이후 토스증권 PC에서 발급받는 구조이며, 신청과 발급 시점이 다를 수 있다.
시세·종목·시장 정보
- 국내 KRX 및 미국 주식의 현재가, 호가, 최근 체결, 상·하한가를 조회할 수 있다.
- 캔들은
1m,1d단위로 최대 200개까지 조회한다. - 종목 기본 정보는 최대 200개 심볼을 콤마로 묶어 조회할 수 있다.
- 종목명, 시장, 통화, 상장 상태, 발행주식수, ETF/ETN 레버리지 배수 같은 참조 정보를 받을 수 있다.
- 매수 유의사항은 정리매매, 단기과열, 투자경고/위험, VI, 신주인수권 등을 포함한다.
- KRW↔USD 환율은 1분 주기 참고용 표시 환율이며 실제 주문 환율과 다를 수 있다.
- 국내 장 캘린더는 KRX+NXT 통합 모드 기준이고, 미국 장 캘린더는 day/pre/regular/after 세션을 제공한다.
계좌·자산
- 정상 상태의 본인 종합매매 계좌 목록을 조회할 수 있다.
- 보유 주식은 국내·미국 주식만 포함하며, 해외 옵션·채권은 제외된다.
- 보유 종목별 수량, 현재가, 평균매입가, 평가금액, 손익, 일간 손익, 비용을 조회할 수 있다.
- 전체 포트폴리오 요약은 원화/달러 합산과 원화 환산 손익률 관점으로 제공된다.
주문·거래 가능 정보
- 국내·미국 주식 매수/매도 주문 생성이 가능하다.
- 지정가(
LIMIT)와 시장가(MARKET)를 지원한다. - 미국 주식은 금액 기반 시장가 주문(
orderAmount)도 가능하며 정규장에만 접수된다. - 미국 주식 LOC 성격의 장 마감 지정가 주문은
LIMIT + CLS조합 예시가 문서에 있다. - 주문 정정과 취소가 가능하다. 국내 주식 정정은 수량 필수, 미국 주식 정정은 가격 변경만 지원한다.
- 주문 상세는 체결 완료, 취소, 거부 등 모든 상태를
orderId로 조회할 수 있다. - 진행 중 주문 목록(
OPEN)은 조회 가능하지만 종료 주문 목록(CLOSED)은 현재 미지원이다. - 매수 가능 금액은 미수거래를 제외한 현금 기반 금액으로 조회한다.
- 종목별 매도 가능 수량과 국내/해외 시장별 매매 수수료율도 조회할 수 있다.
clientOrderId를 넣으면 10분간 멱등성 키로 동작해 중복 주문 방지에 활용할 수 있다.
제한과 주의점
- 현재 연동 방식은 REST API만 제공한다. 웹소켓은 추후 지원 예정으로 표시되어 있다.
- API로 입출금과 환전은 할 수 없다.
- 만 19세 미만은 API 거래를 이용할 수 없다.
- 본인 매매 목적만 허용되며 외부 배포나 상업적 용도로 사용할 수 없다.
- 계좌 목록은 현재 종합매매(
BROKERAGE) 계좌만 노출되고 자녀계좌는 사용할 수 없다. - 국내 주문은 투자자지시 거래소 설정이 통합(SOR)이어야 하는 제한이 있다.
- 1억원 이상 주문은
confirmHighValueOrder=true확인 플래그가 필요하고, 국내 30억원 초과 주문은 거절될 수 있다. - 동일 종목에 반대 방향 미체결 주문이 있으면 주문이 거절될 수 있다.
- 종목 거래 제한, 주문 가능 시간 외, 가격 허용 범위 초과, 사전 자격 요건 미충족 등으로 주문이 거절될 수 있다.
- 시세 데이터는 거래소나 데이터 벤더 사정에 따라 지연 또는 오차가 있을 수 있다.
- 자동화 반복 매매·알고리즘 매매 자체를 설명하고 있지만, 그로 인한 주문 오류·중복 주문·손실은 투자자 본인 책임으로 명시되어 있다.
Rate limits
| 그룹 | 기본 한도 |
|---|---|
AUTH | 초당 5회 |
ACCOUNT | 초당 1회 |
ASSET | 초당 5회 |
STOCK | 초당 5회 |
MARKET_INFO | 초당 3회 |
MARKET_DATA | 초당 10회 |
MARKET_DATA_CHART | 초당 5회 |
ORDER | 초당 6회, 09:00~09:10 KST는 초당 3회 |
ORDER_HISTORY | 초당 5회 |
ORDER_INFO | 초당 6회, 09:00~09:10 KST는 초당 3회 |
한도는 클라이언트 × API 그룹 단위로 적용되며 운영 상황에 따라 바뀔 수 있다. 실제 허용 한도는 X-RateLimit-Limit, 잔여량은 X-RateLimit-Remaining, 재시도는 429 응답의 Retry-After로 확인한다.
활용 가능성 판단
- 포트폴리오 분석/리밸런싱 보조: 가능. 계좌·보유·시세·환율·수수료를 조합할 수 있다.
- 개인용 자동매매: 가능 범위가 넓다. 주문 생성·정정·취소와 매수 가능 금액/매도 가능 수량 조회가 있다. 다만 본인 책임, 호출 한도, 주문시간, 주문 제한을 강하게 고려해야 한다.
- AI 투자비서 연동: 가능. 공식 문구도 외부 애플리케이션이나 AI 도구에서 본인 API Key로 본인 정보를 호출하는 구조를 설명한다.
- 상용 투자 앱/SaaS/타인 계좌 연결: 현재 공개 문구상 부적합하다. 본인 매매 목적만 허용되고 외부 배포·상업적 용도는 제한된다.
- 초고빈도/틱 스트리밍 시스템: 부적합하다. 웹소켓이 없고 초당 호출 한도가 낮으며 REST polling 기반이다.