# WebSocket 연결과 공통 규칙

외부 WebSocket은 운영 환경에서 **`wss://api-ws.btxpro.co.kr`** 호스트를 사용합니다. REST의 `api.btxpro.co.kr`와 구분해서 사용합니다.

| 스트림 | 전체 연결 주소 | 용도 |
| --- | --- | --- |
| 공개 | `wss://api-ws.btxpro.co.kr/v1/market/stream` | ticker 구독·해제 |
| 개인 | `wss://api-ws.btxpro.co.kr/v1/user/stream` | 주문·체결·잔고 수신과 주문 명령 |

공개·개인 스트림은 별도 연결입니다. 개인 주문 명령은 개인 이벤트를 수신하는 **동일 연결**로 전송합니다. 별도 거래용 호스트나 경로는 없습니다.

## 연결 방법

- 공개 스트림은 키 없이 HTTP GET을 WebSocket으로 업그레이드합니다. 쿼리 파라미터는 받지 않습니다.
- 개인 스트림은 GET 업그레이드 요청에 [인증 헤더](/api-docs/guide/authentication.md#websocket-authentication)를 포함합니다.
- 연결 후에는 UTF-8 JSON 텍스트 프레임을 사용합니다.
- 공개 스트림은 `subscribe`를 보내야 시세를 받습니다. 개인 스트림은 연결 직후 `snapshot`을 받으며 별도 subscribe가 없습니다.

## heartbeat와 제한 {#heartbeat-and-limits}

| 항목 | 제한 |
| --- | --- |
| 서버 ping | 30초마다 WebSocket 제어 프레임 |
| pong 제한 | 75초 |
| 공개 명령 크기 | 8 KiB |
| 개인 명령 크기 | 16 KiB |
| 명령 ID | `[A-Za-z0-9._:-]+`, 최대 64자 |
| 공개 구독 | 개별 symbol 최대 100개 또는 wildcard 하나 |
| 개인 명령 대기열 | 연결당 32개 |
| 공개·개인 이벤트 큐 | 각각 256개 / 128개 |
| 개인 키·권한 재확인 | 명령마다, 유휴 연결은 60초마다 |

라이브러리의 ping/pong 처리를 사용하세요. JSON `{"op":"ping"}` 명령은 프로토콜에 없습니다. 서버가 이벤트를 보내는 속도를 따라가지 못하면 `1013 / EVENT_BUFFER_OVERFLOW`로 종료됩니다.

## sequence와 명령 ID

공개 데이터 이벤트는 연결마다 `sequence: 1`부터 연속 증가합니다. 개인 연결은 초기 `snapshot`이 0, 이후 `order`·`fill`·`balance`가 공통 sequence로 1부터 연속 증가합니다.

구독 확인이나 개인 명령의 `response`·`error`는 데이터 sequence를 사용하지 않습니다. 개인 주문 이벤트가 명령 성공 응답보다 먼저 도착할 수도 있습니다. 명령 `id`와 데이터 `sequence`를 별도로 추적하세요.

## 다음 가이드

- [공개 시세: subscribe, unsubscribe, ticker](/api-docs/websocket/market.md)
- [개인 이벤트: snapshot, order, fill, balance](/api-docs/websocket/user.md)
- [주문 명령: create, cancel, amend](/api-docs/websocket/commands.md)
- [재연결과 상태 복구](/api-docs/websocket/recovery.md)
- [모든 메시지 스키마](/api-docs/generated/websocket.md)