WebSocket 서버에 접속하여 실시 간 시세 데이터를 구독하는 방법을 안내합니다. Public Channel은 별도 인증 없이 접속 가능하며, 전체 종목 시세, 호가, OHLC Ticker 데이터를 수신할 수 있습니다.
접속 정보#
| 항목 | 값 |
|---|
| Endpoint | wss://app.moda-orbis.com/ws/open-api |
| 인증 | 불필요 (Public Channel) |
| 데이터 형식 | Protobuf (바이너리) |
| binaryType | arraybuffer (필수) |
주의
binaryType은 반드시 arraybuffer로 설정해야 합니다. 서버로부터 수신되는 모든 메시지는 바이너리 프레임으로 전송됩니다.
참고
JWT 없이 시세 구독 시 기본 등급(000) 스프레드가 적용됩니다. 계좌 인증이 필요한 경우 POST /open/v1/auths/ws-token으로 발급받은 토큰을 사용하세요.
연결 예제#
제공 파일#
서버에서 수신되는 Protobuf 메시지를 디코딩하기 위한 클라이언트 라이브러리 파일이 제공됩니다. 런타임에 protobufjs 패키지가 필요합니다.| 파일명 | 용도 |
|---|
realtime_message_browser.js | 브라우저 환경 (IIFE, window.protobuf 사용) |
realtime_message_esm.js | ES Module 환경 (import/export) |
realtime_message_cjs.js | CommonJS 환경 (Node.js require) |
realtime_message_d.ts | TypeScript 타입 정의 |
채널 구독 / 해제#
WebSocket 연결 완료 후, JSON 텍스트 프레임을 전송하여 채널을 구독하거나 해제합니다.요청 파라미터#
| 필드 | 필수 | 타입 | 설명 |
|---|
action | O | string | SUBSCRIBE / UNSUBSCRIBE |
channels | O | string[] | 구독할 채널명 배열 |
options.stockCd | 조건부 | string | market.orderbook 구독 시 필수 |
구독 요청 예제#
{
"action": "SUBSCRIBE",
"channels": ["market.quote"]
}
{
"action": "SUBSCRIBE",
"channels": ["market.orderbook"],
"options": { "stockCd": "A005930" }
}
{
"action": "SUBSCRIBE",
"channels": ["market.quote", "market.ticker"]
}
해제 요청 예제#
{
"action": "UNSUBSCRIBE",
"channels": ["market.quote"]
}
사용 가능한 채널#
| 채널명 | 설명 | 비고 |
|---|
market.quote | 전체 종목 실시간 시세 | — |
market.orderbook | 종목별 5단계 호가 | options.stockCd 필수 |
market.orderbook.cancel | 호가 취소 이벤트 | — |
market.ticker | OHLC Ticker | — |
메시지 수신 포맷#
서버에서 수신되는 모든 메시지는 바이너리 프레임이며, 다음 구조로 인코딩됩니다.[1 byte 타입코드] + [Protobuf 인코딩 페이로드]
타입코드 목록#
| 타입코드 | Protobuf 메시지 | 설명 |
|---|
1 | MarketQuoteList | 전체 종목 시세 |
2 | MarketOrderBook | 종목별 호가 (5단계) |
3 | OrderBookCancel | 호가 취소 |
9 | MarketTickerList | OHLC Ticker |
디코딩 예제#
데이터 스키마#
모든 숫자 필드는 string 타입으로 전송됩니다.MarketQuote (시세)#
MarketQuoteList.quotes 배열의 원소입니다.| 필드명 | 타입 | 설명 |
|---|
stockCd | string | 종목 코드 |
buy | string | 매수 호가 |
sell | string | 매도 호가 |
buySize | string | 매수 잔량 |
sellSize | string | 매도 잔량 |
timestamp | number|Long | 타임스탬프 (epoch ms) |
MarketQuoteList#
| 필드명 | 타입 | 설명 |
|---|
quotes | MarketQuote[] | MarketQuote 배열 |
Quote (호가 단계)#
MarketOrderBook.quotes 배열의 원소입니다.| 필드명 | 타입 | 설명 |
|---|
buy | string | 매수 호가 |
sell | string | 매도 호가 |
buySize | string | 매수 잔량 |
sellSize | string | 매도 잔량 |
MarketOrderBook (호가)#
타입코드 2. 종목별 5단계 호가 데이터입니다.| 필드명 | 타입 | 설명 |
|---|
stockCd | string | 종목 코드 |
quotes | Quote[] | 5단계 호가 배열 |
timestamp | number|Long | 타 임스탬프 (epoch ms) |
OrderBookCancel (호가 취소)#
| 필드명 | 타입 | 설명 |
|---|
cancelType | string | 취소 유형: ALL | STOCK_CD |
stockCd | string | 종목 코드 (cancelType이 STOCK_CD일 때) |
timestamp | number|Long | 타임스탬프 (epoch ms) |
MarketTicker (OHLC)#
MarketTickerList.tickers 배열의 원소입니다.| 필드명 | 타입 | 설명 |
|---|
stockCd | string | 종목 코드 |
date | string | 날짜 |
open | string | 시가 |
high | string | 고가 |
low | string | 저가 |
close | string | 현재가 / 종가 |
beforeClose | string | 전일 종가 |
lastUpdated | string | 마지막 업데이트 시각 |
MarketTickerList#
타입코드 9. OHLC Ticker 목록입니다.| 필드명 | 타입 | 설명 |
|---|
tickers | MarketTicker[] | MarketTicker 배열 |
주의사항#
| 항목 | 내용 |
|---|
| 스프레드 등급 | JWT 없이 구독 시 기본 등급(000) 스프레드 적용 |
| 호가 구독 | market.orderbook 구독 시 options.stockCd 누락하면 validation 에러 |
| 재연결 | 연결 끊김 시 서버가 세션·구독 정보를 자동 정리. 재연결 후 구독 재전송 필요 |
| 메시지 디코딩 | 첫 번째 바이트를 타입코드로 읽고, 나머지를 Protobuf 메시지로 디코딩 |
