토스증권 오픈API 자동매매 — 발급·주문·호출한도 정리

국내 개인 자동매매는 오랫동안 한국투자증권 KIS API·키움 REST API·LS증권·대신 네 곳으로 굳어 있었습니다. 여기에 토스증권이 개인 개발자용 OpenAPI를 열면서 선택지가 하나 늘었습니다. 이 글은 마케팅 문구가 아니라 토스증권이 공개한 OpenAPI 3.0 명세서와 공식 개요 문서를 그대로 읽고, 봇을 붙일 때 실제로 필요한 것만 정리한 것입니다. (본문 스펙은 2026-08-04 확인 기준이며, 정책·한도는 변경될 수 있으니 최종 확인은 공식 문서에서 하세요.)

다른 증권사와 성격을 비교하려면 증권사 API 비교 2026을, 이미 KIS로 만들다 온 상태라면 KIS API 발급 30분 완성과 나란히 두고 보면 차이가 빨리 잡힙니다.

기존 증권사 API와 결정적으로 다른 4가지

KIS나 키움을 만져 본 사람이 토스증권 OpenAPI에서 가장 먼저 체감하는 차이는 "업무 코드가 없다"는 점입니다. KIS API는 같은 주소에 tr_id를 바꿔 끼우며 업무를 구분하고(TTTC0802U는 국내주식 현금 매수), 키움 OpenAPI+는 32bit OCX를 거쳐야 했습니다. 토스증권은 URL이 곧 기능인 평범한 REST API입니다.

실무적으로 가장 큰 갈림길은 실시간입니다. 공식 개요 문서는 "토스증권 Open API 는 현재 REST API 만 제공합니다"라고 못 박고 있습니다. 초 단위로 호가 변화에 반응해야 하는 전략이라면 폴링 간격이 곧 전략의 한계가 되므로, WebSocket 채널이 있는 KIS API·키움 REST API 쪽과 저울질해야 합니다. 반대로 하루 몇 번 규칙대로 사고파는 리밸런싱·분할매수형이라면 REST만으로 충분합니다.

발급 4단계 — 허용 IP를 빼먹으면 403

공용인증서 절차 없이 웹에서 끝납니다. 순서는 이렇습니다.

1. 클라이언트 등록 — 토스증권 WTS(PC 웹) 로그인 → 설정 → Open API → client_id·client_secret 발급
2. 허용 IP 등록 — 같은 메뉴 하단 허용 IP 관리에서 봇이 돌 서버의 공인 IP 등록
3. 액세스 토큰 발급 — POST /oauth2/token
4. 호출 — Authorization: Bearer (+ 계좌 계열은 X-Tossinvest-Account)

첫 호출 — 토큰만 되는 것과 계좌 헤더가 필요한 것

토큰 발급은 폼 인코딩입니다. JSON으로 보내면 막힙니다.

# 1) 액세스 토큰
curl -s -X POST 'https://openapi.tossinvest.com/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=xxx' -d 'client_secret=yyy'

# 응답
{"access_token":"eyJraWQiOiIyMDI2LTA0LTAxLWtleSI...",
 "token_type":"Bearer","expires_in":86400}

expires_in이 86400초(24시간)입니다. KIS와 마찬가지로 매 호출마다 토큰을 새로 받으면 AUTH 그룹 한도(초당 5회)에 금방 부딪히므로, 토큰은 캐시하고 만료 전에만 갱신하는 구조로 짜야 합니다.

import os, time, requests

BASE = "https://openapi.tossinvest.com"
_tok = {"v": None, "exp": 0}

def token():
    if _tok["v"] and time.time() < _tok["exp"] - 300:   # 5분 여유
        return _tok["v"]
    r = requests.post(f"{BASE}/oauth2/token",
        data={"grant_type": "client_credentials",
              "client_id": os.environ["TOSS_CLIENT_ID"],
              "client_secret": os.environ["TOSS_CLIENT_SECRET"]},
        timeout=5)
    r.raise_for_status()
    d = r.json()
    _tok["v"], _tok["exp"] = d["access_token"], time.time() + d["expires_in"]
    return _tok["v"]

def headers(account=None):
    h = {"Authorization": f"Bearer {token()}"}
    if account:                       # 계좌·자산·주문·조건주문 계열
        h["X-Tossinvest-Account"] = str(account)
    return h

# 시세 — 토큰만
requests.get(f"{BASE}/api/v1/prices", params={"symbols": "005930"},
             headers=headers(), timeout=5)

# 보유 주식 — 계좌 헤더 필요
requests.get(f"{BASE}/api/v1/holdings", headers=headers(1), timeout=5)

응답은 성공이면 {"result": ...} 봉투로, 실패면 {"error": {...}} 봉투로 옵니다. 이 봉투 구조와 에러 코드별 대응은 토스증권 오픈API 에러코드 12가지에서 따로 다뤘습니다.

주문 만들기 — 필드 8개와 미국 주식 소수점·LOC

주문 생성은 POST /api/v1/orders 하나이고, 바디에 쓰는 필드는 실질적으로 8개입니다.

// 국내주식 지정가 매수
{"clientOrderId":"my-order-001","symbol":"005930",
 "side":"BUY","orderType":"LIMIT","quantity":"10","price":"70000"}

// 미국주식 금액 기준 시장가 매수 (정규장만)
{"symbol":"AAPL","side":"BUY","orderType":"MARKET","orderAmount":"100.5"}

// 미국주식 소수점 시장가 매도
{"symbol":"AAPL","side":"SELL","orderType":"MARKET","quantity":"0.5"}

// 미국주식 종가 지정가 = LIMIT + CLS
{"symbol":"AAPL","side":"BUY","orderType":"LIMIT",
 "timeInForce":"CLS","quantity":"10","price":"185.5"}

자동매매 관점에서 진짜 중요한 필드는 clientOrderId입니다. 이 값을 넣어 두면 같은 값으로 재요청했을 때 이전 주문 결과를 그대로 돌려줍니다. 타임아웃이 났는데 주문이 들어갔는지 알 수 없는 상황 — 봇이 중복 주문을 내는 가장 흔한 사고 — 를 이 한 필드가 막습니다. 서버가 자동 생성해 주지 않으므로 봇이 직접 만들어 넣어야 하고, 유효 기간은 10분입니다.

조건주문 SINGLE · OCO · OTO

토스증권 OpenAPI에서 눈여겨볼 부분입니다. 보통 손절·익절은 봇이 시세를 계속 보다가 조건이 맞으면 주문을 던지는데, 여기서는 조건 자체를 서버에 등록할 수 있습니다. 봇이 죽어 있어도 감시는 살아 있다는 뜻이라, REST 전용이라는 약점을 일부 상쇄합니다.

• SINGLE — 감시가에 도달하면 주문 1건
• OCO — 두 조건 중 하나가 체결되면 나머지 취소(익절/손절 동시 대기)
• OTO — 첫 주문이 체결되면 두 번째 주문이 등록(매수 후 자동 익절)

// OCO — 익절 305, 손절 295 동시 대기 (first 감시가 > 현재가 > second 감시가)
POST /api/v1/conditional-orders
{"symbol":"005930","type":"OCO","quantity":"100","orderType":"LIMIT",
 "clientOrderId":"my-order-003","expireDate":"2026-09-10",
 "first": {"orderSide":"SELL","triggerPrice":"305","orderPrice":"305"},
 "second":{"orderSide":"SELL","triggerPrice":"295","orderPrice":"294.5"}}

// OTO — 290에 사고, 체결되면 320 매도 예약
{"symbol":"005930","type":"OTO","quantity":"100","orderType":"LIMIT",
 "clientOrderId":"my-order-004","expireDate":"2026-09-10",
 "first": {"orderSide":"BUY","triggerPrice":"290","orderPrice":"290"},
 "second":{"orderSide":"SELL","triggerPrice":"320","orderPrice":"320"}}

제약이 하나 있습니다. OCO와 OTO는 종목당 1개입니다(둘째를 등록하면 duplicate-conditional-order). SINGLE은 개수 제한이 없습니다. 그리고 이미 조건을 충족한 가격으로 등록하면 condition-already-met으로 거부되므로, 등록 직전에 현재가를 한 번 읽고 넣는 편이 안전합니다. 익절·손절 폭 자체를 어떻게 잡을지는 전략 설계의 문제라 API와는 별개입니다.

호출 한도 — 그룹별 TPS와 9시대 함정

한도가 계정 전체 하나로 묶여 있지 않고 클라이언트 × API 그룹으로 쪼개져 있습니다. 시세를 아무리 많이 읽어도 주문 한도를 갉아먹지 않는다는 뜻이라 설계가 편합니다. 공식 문서에 표기된 값은 이렇습니다(2026-08-04 확인, 사전 공지 없이 조정될 수 있음).

함정이 둘 있습니다. 첫째, ACCOUNT가 초당 1회입니다. 계좌 목록은 시작할 때 한 번 읽고 캐시해야지, 루프 안에서 부르면 바로 막힙니다. 둘째, ORDER_INFO가 장 시작 10분간 절반으로 줄어듭니다. 매수 가능 금액을 매 주문마다 확인하는 구조라면 하필 가장 바쁜 시간에 429를 맞습니다.

// 429 응답 — 헤더를 보고 판단한다
X-RateLimit-Limit: 6
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1
Retry-After: 1

{"error":{"requestId":"01HXYZABCDEFG123456789",
  "code":"rate-limit-exceeded","message":"요청이 너무 많습니다."}}

권장 대응도 문서에 적혀 있습니다 — Retry-After만큼 대기 후 재시도, 지수 백오프(1s → 2s → 4s)에 지터를 섞을 것, X-RateLimit-Remaining이 줄어들면 선제적으로 속도를 늦출 것. 전략을 여러 개 돌리면 호출량이 합산된다는 점까지 포함한 설계는 API 호출 제한 설계에 정리해 두었습니다. KIS의 EGW00201(초당 거래건수 초과)과 원인은 같고 이름만 다릅니다.

붙이기 전 체크리스트 7개

1. 봇이 돌 서버의 공인 IP를 허용 IP에 등록했는가 (VPS 이전 시 재등록)
2. access_token을 캐시하고 만료 5분 전에만 갱신하는가
3. 계좌 목록(ACCOUNT, 초당 1회)을 기동 시 1회만 읽는가
4. 모든 주문에 clientOrderId 멱등키가 붙는가
5. 429를 받았을 때 Retry-After + 지수 백오프로 재시도하는가
6. 실시간이 없다는 전제로 폴링 주기가 전략과 맞는가
7. 실패 응답의 code와 requestId가 로그에 그대로 남는가 (CS 문의 시 requestId 첨부 권장)

자주 묻는 질문

토스증권 OpenAPI 문서는 어디서 보나요?

개발자 포털의 인터랙티브 레퍼런스와 함께, 기계가 읽는 형식이 같이 공개돼 있는 것이 특징입니다. 사람이 읽는 개요 마크다운, LLM용 API 레퍼런스 마크다운, 그리고 OpenAPI 3.0 JSON 명세 세 가지가 있고, 문서 스스로 JSON을 최종 기준(source of truth)이라고 밝히고 있습니다. 스펙이 바뀌었는지 확인할 때는 이 JSON을 받아 비교하는 것이 가장 정확합니다.

KIS나 키움에서 만든 봇을 그대로 옮길 수 있나요?

전략 로직은 그대로 쓰지만 통신 계층은 새로 짜야 합니다. tr_id·appkey·custtype 같은 KIS 고유 헤더가 사라지고, 계좌 지정이 바디에서 X-Tossinvest-Account 헤더로 올라오며, 실시간 WebSocket 콜백이 폴링 루프로 바뀝니다. 증권사마다 통신 규격이 다르다는 점은 키움 OpenAPI+와 KIS API 사이에서도 똑같이 겪는 문제입니다.

API 이용료가 있나요?

공식 OpenAPI 명세에는 요금 항목이 없고, 대신 GET /api/v1/commissions로 매매 수수료를 시장별(KR·US)로 조회하는 엔드포인트가 있습니다. API 이용료·데이터 이용료 정책은 증권사마다 다르고 수시로 바뀌므로 숫자를 단정하지 않겠습니다 — 토스증권 공식 고지에서 확인하세요.

자동매매를 하면 수익이 나나요?

API가 열렸다는 것은 주문을 코드로 낼 수 있다는 뜻이지 수익과는 다른 이야기입니다. 과거 성과나 백테스트 결과가 미래 수익을 보장하지 않으며, 이 글의 어떤 내용도 특정 종목·방향에 대한 투자 권유가 아닙니다. API는 실행을 자동화할 뿐, 전략의 유효성은 별도로 검증해야 합니다.