토스증권 웹소켓 API — 연결 2개·PING 함정 7가지

공개 초기 토스증권 Open API는 REST만 있어서 그 무렵 자료에는 지금도 "실시간은 폴링"이라고 적혀 있습니다. 이 글은 토스증권 오픈API 가이드(허브)의 웹소켓 절을 봇 코드 수준으로 풀어 쓴 스포크입니다. 발급·허용 IP·REST 호출 한도는 허브를 먼저 보세요.

1. 연결 — 주소·헤더·handshake 상태코드

주소는 wss://openapi-ws.tossinvest.com/ws/v1 하나입니다. REST 서버(openapi.tossinvest.com)와 호스트가 다릅니다. 인증은 POST /oauth2/token(OAuth 2.0 client_credentials)으로 받은 REST용 access_token을 handshake 헤더 Authorization: Bearer에 그대로 넣습니다. TLS 필수이고, 허용 IP 목록도 REST와 같은 것이 적용됩니다.

연결된 뒤의 실패는 전부 프레임 안의 error로 옵니다. 그리고 인증은 handshake 때 1회뿐이라, 연결 중에 토큰이 만료돼도 연결은 끊기지 않습니다. 반대로 말하면 재연결 순간에는 새 토큰이 필요합니다. 재연결 루프 안에서 토큰 캐시를 확인하지 않으면 "몇 시간 잘 돌다가 재연결부터 계속 401"이 됩니다.

2. 함정 ① 구독은 full-replace

KIS 웹소켓(tr_type 1/2)이나 키움 REST 웹소켓(REG/REMOVE)에 익숙하면 여기서 먼저 걸립니다. 토스에는 subscribe·unsubscribe 액션이 없습니다. 보낸 JSON 배열 1개가 곧 현재 구독 전체이고, 새 배열이 오면 기존 구독을 통째로 대체합니다.

// 송신 — 구독 선언 (배열 1개, 여러 채널 혼합 가능)
[
  {"id": "req-1"},
  {"type": "trade:kr", "codes": ["005930"]},
  {"type": "orderbook:kr", "codes": ["005930"]},
  {"type": "personal:order", "codes": ["3"]}
]

// 수신 — 데이터보다 먼저 오는 ack
{"type": "subscriptions", "id": "req-1",
 "subscribed": ["trade:kr:005930", "orderbook:kr:005930", "personal:order:3"],
 "rejected": []}

이 상태에서 SK하이닉스를 더하려고 [{"type":"trade:kr","codes":["000660"]}]만 보내면, 삼성전자 체결·호가와 주문 이벤트 구독이 전부 해제되고 000660 하나만 남습니다. 에러도 나지 않습니다. 봇이 "현재 구독 목록"을 들고 있다가 매번 전체를 다시 보내야 합니다.

수신 프레임의 topic은 type 뒤에 코드를 :로 붙인 값(trade:kr:005930)이라, ack의 subscribed와 같은 문자열로 라우팅하면 됩니다. {"id": "req-1"}은 선택 원소로, ack와 error에 그대로 돌아옵니다.

3. 함정 ② 연결은 계정당 2개

동시 연결 한도는 계정당 2개입니다. 3번째를 열면 새 연결이 거부되는 게 아니라 새 연결은 수락되고 가장 오래된 연결이 서버에 의해 종료됩니다. 그리고 이 종료에는 별도 close code가 없어 클라이언트에는 그냥 비정상 종료로 보입니다.

실전 봇과 대시보드가 붙어 있을 때 테스트 스크립트를 하나 띄우면 실전 봇이 끊기고, 재연결하면 이번엔 대시보드가 끊기는 식으로 서로를 밀어냅니다. 공식 문서도 "재연결 전에 쓰던 연결을 먼저 닫으라"고 따로 적어 둡니다. 한 계정에 붙는 프로세스는 2개 이하로 설계하고, 여러 전략이 시세를 나눠 써야 하면 연결 1개가 받아서 내부로 뿌리는 구조가 맞습니다.

구독 수는 연결당 100건이고 채널×종목 조합으로 셉니다. trade:kr:005930과 orderbook:kr:005930은 2건이고, personal:order의 accountSeq도 1건으로 들어갑니다. 체결·호가를 둘 다 받으면 종목은 최대 49개 남짓입니다(주문 1건 포함 시). 선언 빈도는 초당 5회입니다.

4. 함정 ③ PING은 텍스트, 180초

서버는 클라이언트로부터 180초간 아무것도 받지 못하면 연결을 끊습니다. 여기서 중요한 건 방향입니다. 서버가 체결을 계속 보내 줘도 이 타이머는 리셋되지 않습니다. 시세가 잘 들어오는데 정확히 3분마다 끊긴다면 이 문제입니다.

> PING
< {"type":"pong"}

보내는 쪽은 JSON이 아니라 따옴표 없는 텍스트 PING(대문자 4글자)입니다. {"type":"ping"}이나 ["PING"]처럼 감싸 보내면 구독 선언으로 해석돼 wrong-format을 받게 됩니다. 공식 권장 간격은 60초입니다. 공식 문서는 웹소켓 표준 ping/pong 프레임도 지원한다고 적고 있고, 파이썬 websockets 라이브러리(14.2 기준)는 기본값 ping_interval=20으로 표준 ping을 자동으로 보냅니다. 그래도 명시된 텍스트 PING을 따로 보내는 쪽이 안전합니다.

5. 함정 ④⑤ 스냅샷 없음·시세 LOSSY

④ 구독 직후 초기 스냅샷이 오지 않습니다. 다음 체결·다음 호가 갱신부터 옵니다. 봇이 시작 시점의 가격이 필요하면 REST GET /api/v1/trades(체결)·GET /api/v1/orderbook(호가)로 먼저 읽고 웹소켓으로 이어 받습니다.

⑤ 시세 채널은 LOSSY입니다. 수신이 밀리면 중간 프레임이 버려지고 항상 최신 상태가 우선입니다. 유실을 감지할 sequence 필드도 없습니다. 체결 프레임 실물은 이렇습니다.

{"type": "message", "topic": "trade:us:AAPL",
 "data": {"price": "243.26", "volume": "8",
          "timestamp": "2026-06-18T23:30:00.000+09:00", "currency": "USD"}}

{"type": "message", "topic": "orderbook:kr:005930",
 "data": {"timestamp": "2026-06-18T23:30:00.000+09:00", "currency": "KRW",
          "asks": [{"price": "71500", "volume": "5"}],
          "bids": [{"price": "71400", "volume": "10"}]}}

체결 필드는 네 개뿐입니다. 누적 거래량도, 매수·매도 체결 구분도 없습니다. 프레임을 더해서 누적 거래량을 만들거나 체결강도를 계산하는 설계는 유실 때문에 성립하지 않습니다 — 공식 문서도 누적값은 REST 캔들·현재가를 쓰라고 적고 있습니다. 숫자는 전부 문자열(format: decimal)이라 Decimal이나 float로 바꿔 써야 합니다. 국내(kr)는 KRX 정규장과 NXT 프리·정규·애프터마켓을 합친 통합 시세만 나옵니다. KRX만 따로 받을 수 없으니 KRX 기준 신호를 쓰는 전략은 이 점을 먼저 확인해야 합니다(KIS의 KRX·NXT·통합 TR 구분과 비교해 보세요).

6. 함정 ⑥⑦ personal:order — accountSeq와 이벤트명

⑥ codes에는 종목이 아니라 계좌 accountSeq를 넣습니다. 값은 GET /api/v1/accounts 응답에서 얻는데, 거기서는 숫자로 오고 codes는 문자열 배열입니다. 3이 아니라 "3"으로 바꿔야 하고, 숫자로 넣으면 no-codes(비문자열 원소)입니다. 본인 종합매매·활성 계좌만 되고, 전달되는 것은 국내·미국 주식 주문뿐입니다.

⑦ 이벤트명(data.event)과 주문 상태명(data.order.status)이 서로 다른 단어입니다. REST 주문 조회에 맞춰 짠 상태 머신에 웹소켓 이벤트를 그대로 넣으면 몇 개가 매칭되지 않습니다.

{"type": "message", "topic": "personal:order:3",
 "data": {"event": "FILL", "accountSeq": "3",
          "order": {"orderId": "bAGzNvMOOTa5Uy0x...", "symbol": "AAPL", "side": "BUY",
                    "orderType": "LIMIT", "timeInForce": "DAY", "status": "FILLED",
                    "price": "100.5", "quantity": "10", "currency": "USD",
                    "execution": {"filledQuantity": "10", "averageFilledPrice": "100",
                                  "commission": "1.23", "tax": "0",
                                  "settlementDate": "2026-06-25"}}}}

판정은 data.order.status로 하는 편이 낫습니다. REST GET /api/v1/orders/{orderId}와 같은 어휘라 재동기화 코드와 공유할 수 있기 때문입니다. 단 웹소켓 쪽 order에는 execution.filledAt(체결 시각)이 빠져 있습니다. 공식 문서는 enum 전부에 "클라이언트는 unknown code를 허용하도록 구현해야 한다"고 적고 있으니, 모르는 값이 오면 죽지 말고 로그만 남기게 짜야 합니다. 정정하면 orderId가 새로 생기는 점은 토스 주문 취소·정정에서 따로 다뤘습니다.

7. 에러 프레임 12가지와 대응

선언 전체가 실패하면 error 프레임(기존 구독은 유지), 일부만 실패하면 ack의 rejected[]로 옵니다.

{"type": "error", "error": {"code": "no-codes",
 "message": "codes must be a non-empty array of strings"}, "id": "req-1"}

REST 쪽 에러(401·422·429 등)는 토스증권 오픈API 에러코드에 정리돼 있습니다.

8. 재연결까지 넣은 파이썬 클라이언트

위 일곱 가지를 한 클래스에 넣으면 이렇게 됩니다. 구독 목록을 봇이 들고 있다가 추가할 때마다 전체를 보내고, 거부된 항목은 목록에서 빼고, 60초마다 텍스트 PING, 끊기면 지수 백오프 후 같은 목록으로 재선언합니다. websockets 14.2의 websockets.asyncio.client.connect(13.0 이상) 기준이고, 12.x 이하의 옛 인터페이스는 헤더 인자 이름이 extra_headers입니다.

import asyncio, json, random
from websockets.asyncio.client import connect   # websockets 13.0+

WS_URL = "wss://openapi-ws.tossinvest.com/ws/v1"

class TossStream:
    PING_SEC = 60                            # 공식 권장 60초 (한도 180초)

    def __init__(self, get_token, url=WS_URL):
        self.get_token = get_token           # handshake 때만 쓰인다 → 재연결마다 다시 호출
        self.url = url
        self.subs = {}                       # {"trade:kr": {"005930"}, ...} = 현재 구독 전체
        self.ws = None
        self.seq = 0

    def declaration(self):
        self.seq += 1
        body = [{"id": f"req-{self.seq}"}]
        for t, codes in self.subs.items():
            if codes:
                body.append({"type": t, "codes": sorted(codes)})
        return json.dumps(body)

    async def add(self, type_, *codes):      # 추가도 전체 목록을 다시 보낸다
        self.subs.setdefault(type_, set()).update(str(c) for c in codes)
        if self.ws:
            await self.ws.send(self.declaration())

    async def keepalive(self, ws):
        while True:
            await asyncio.sleep(self.PING_SEC)
            await ws.send("PING")            # JSON 아님 — 대문자 텍스트

    async def run(self, on_message):
        backoff = 1
        while True:
            try:
                headers = {"Authorization": f"Bearer {self.get_token()}"}
                async with connect(self.url, additional_headers=headers) as ws:
                    self.ws, backoff = ws, 1
                    await ws.send(self.declaration())
                    ka = asyncio.create_task(self.keepalive(ws))
                    try:
                        async for raw in ws:
                            f = json.loads(raw)
                            if f["type"] == "subscriptions":
                                for r in f["rejected"]:      # 다시 보내도 또 거부된다
                                    t, code = r["target"].rsplit(":", 1)
                                    self.subs.get(t, set()).discard(code)
                            elif f["type"] == "error":
                                code = f["error"]["code"]
                                if code == "server-shutdown":
                                    break
                                if code == "rate-limit-exceeded":
                                    await asyncio.sleep(1)   # Retry-After 없음
                                    await ws.send(self.declaration())
                            elif f["type"] == "message":
                                await on_message(f["topic"], f["data"])  # 오래 막지 말 것
                    finally:
                        ka.cancel()
            except Exception as e:
                print("disconnected:", type(e).__name__, e)
            self.ws = None
            await asyncio.sleep(backoff + random.random())
            backoff = min(backoff * 2, 60)

add가 str()로 바꾸므로 accountSeq를 숫자로 넘겨도 됩니다. personal:order를 쓴다면 재연결 직후 GET /api/v1/orders 재동기화를 run 안의 선언 다음 줄에 넣으세요. 토큰 발급과 캐시는 토스증권 API 파이썬 첫 주문의 코드를 그대로 쓰면 됩니다.

이 클래스는 공식 AsyncAPI 규칙(full-replace·rejected·텍스트 PING·server-shutdown)을 흉내 낸 로컬 모의 서버에 붙여 2026-10-15에 돌려 봤습니다. 결과 로그입니다.

('ack', ['trade:kr:005930'], ['trade:kr:999999'])          # 없는 종목만 거부
('ack', ['trade:kr:005930', 'trade:kr:035420'], [])        # 추가 = 전체 재선언
('ping',) ('ping',)
('ack', ['trade:kr:000660', 'trade:kr:005930', 'trade:kr:035420'], [])
('shutdown',)                                               # server-shutdown 수신
('ack', ['trade:kr:000660', 'trade:kr:005930', 'trade:kr:035420'], [])  # 재연결 후 같은 목록
subs: {'trade:kr': {'000660', '035420', '005930'}}          # 999999는 목록에서 빠짐

9. 자주 묻는 질문