업비트 공지사항을 WebSocket으로 수신하기 위한 요청 및 구독 데이터 예시를 제공합니다.
WebSocket Endpoint
| 구분 | Endpoint |
|---|---|
| Private | wss://api.upbit.com/websocket/v1/private |
Private WebSocket 연결 관리 안내Private WebSocket은 동시에 많은 연결을 유지하는 경우 신규 연결이 거절될 수 있습니다.
불필요한 연결 생성을 최소화하고, 가능한 경우 하나의 연결에서 필요한 데이터 타입을 함께 구독해 주세요.
신규 공지 또는 갱신이 없으면 데이터가 전송되지 않습니다.공지사항 데이터는 신규 공지사항이 게시되거나 기존 공지사항이 갱신된 경우에만 실시간으로 전송됩니다. 따라서 WebSocket 연결 후 신규 게시 또는 갱신이 없다면 데이터가 수신되지 않는 것이 정상입니다.
공지사항 데이터는 실시간 스트림만 지원하며,
stream_type은REALTIME로 제공됩니다. WebSocket 연결 및 인증 방법은 WebSocket 사용 및 에러 안내 문서를 참고해주세요.
채널별 공지사항 수신 시점에 차이가 발생할 수 있습니다.서버에서 데이터가 정상적으로 전송되더라도 네트워크 상태나 사용자 환경에 따라 데이터를 정상적으로 수신하지 못할 수 있습니다. 또한 WebSocket을 통한 공지사항 수신 시점은 웹·앱 등 다른 채널의 공지 노출 시점과 다를 수 있으며, 채널별 전송 경로와 시스템 처리 상태, 시스템 보호를 위한 조치 등에 따라 수신 시점에 차이가 발생할 수 있습니다.
Request 메세지 형식
공지사항 데이터 수신을 요청하기 위해서는 WebSocket 연결 이후 아래 구조의 JSON Object를 생성한 뒤 요청 메세지의 Data Type Object로 포함하여 전송해야 합니다.
Ticket, Format 필드를 포함한 전체 WebSocket 데이터 요청 메세지 명세는 WebSocket 사용 및 에러 안내 문서를 참고해주세요.
| 필드명 | 타입 | 내용 | 필수 여부 | 기본 값 |
|---|---|---|---|---|
| type | String | 수신할 데이터 타입. 공지사항 데이터는 announcement로 지정합니다. | Required | |
| categories | List:String | 수신하고자 하는 공지사항 카테고리 목록. 생략할 경우 모든 카테고리의 공지사항을 수신합니다. 지원하지 않는 값을 포함하여 요청하는 경우 INVALID_PARAM 오류가 발생합니다. | Optional | 전체 |
| include_body | Boolean | 공지사항 본문 포함 여부. true로 요청한 경우 구독 데이터에 body 필드가 포함됩니다. 본문 데이터의 용량이 큰 경우 null로 제공될 수 있습니다. | Optional | false |
| format | String | 수신하고자 하는 데이터 포맷입니다. DEFAULT : 기본 포맷.SIMPLE : 간략한 포맷. 각 필드가 축약어 형태로 반환됩니다.JSON_LIST : 리스트 포맷.SIMPLE_LIST : 축약어 형태의 리스트 포맷. | Required |
공지사항 카테고리 (categories)
categories를 지정하면 원하는 카테고리의 공지사항만 구독할 수 있습니다. 별도로 지정하지 않으면 모든 카테고리의 공지사항을 수신합니다.
| 한국어 | 영문 | categories 값 | 설명 |
|---|---|---|---|
| 안내 | Notice | notice | 신규 기능, 기능 개선 등 서비스 이용 관련 공지 |
| 거래 | Trade | trade | 신규 거래지원, 마켓 추가, 거래 유의 촉구·지정 및 거래지원 종료 관련 공지 |
| 입출금 | D/W | wallet | 디지털 자산 입출금 지원, 중단 및 재개 관련 공지 |
| 점검 | Maintenance | maintenance | 시스템 및 서비스 점검 관련 공지 |
| 디지털 자산 | Digital Asset | digital_asset | 에어드랍, 유통량 등 디지털 자산 관련 공지 |
| NFT | NFT | nft | NFT 드롭 관련 공지 |
| 서비스+ | Service+ | service | 업비트 서비스+ 관련 공지 |
| 이벤트 | Event | event | 업비트 이벤트 관련 공지 |
구독 데이터 명세
신규 공지사항이 게시되거나 기존 공지사항이 갱신되는 경우 실시간 스트림 데이터가 아래와 같이 반환됩니다.
| 필드명 | 축약형 | 내용 | 타입 | 값 |
|---|---|---|---|---|
| type | ty | 데이터 타입 | String | announcement |
| event_type | et | 공지사항 이벤트 유형 | String | CREATED : 신규 공지 게시UPDATED : 기존 공지 갱신 |
| uuid | uid | 공지사항의 고유 식별자 | String | |
| title | tt | 공지사항 제목 | String | |
| category | cat | 공지사항 카테고리. | String | 예: trade, wallet, maintenance, service |
| url | url | 공지사항 상세 페이지 URL | String | |
| first_listed_at | flat | 최초 게시 시각 (KST) | String | ISO 8601 |
| listed_at | lat | 최종 게시 시각 (KST) 공지사항이 갱신되는 경우 함께 갱신됩니다. | String | ISO 8601 |
| timestamp | tms | 타임스탬프 (ms) | Long | |
| stream_type | st | 스트림 타입 | String | REALTIME : 실시간 스트림 |
| body | bd | 공지사항 본문(Markdown) 요청 시 include_body를 true로 지정한 경우에만 포함됩니다. | String |
예시
모든 공지사항 구독
카테고리를 지정하지 않고 업비트의 모든 공지사항을 구독하는 예시입니다. 공지사항 본문은 제외하고 수신합니다. ticket은 요청을 식별하기 위한 값으로 원하는 문자열을 직접 지정할 수 있습니다.
구독 요청 예제
[
{
"ticket": "announcement-monitor"
},
{
"type": "announcement",
"include_body": false
},
{
"format": "DEFAULT"
}
]수신 메시지 예제
{
"type": "announcement",
"event_type": "CREATED",
"uuid": "562593104",
"title": "[거래] 신규 거래 지원 안내 ...",
"category": "trade",
"url": "https://www.upbit.com/service_center/notice?id=562593104&view=share",
"first_listed_at": "2026-07-14T16:36:34+09:00",
"listed_at": "2026-07-14T16:36:34+09:00",
"timestamp": 1752566400123,
"stream_type": "REALTIME"
}특정 카테고리 공지사항 구독
categories에 trade를 지정하여 거래 관련 공지사항만 구독하는 예시입니다. 공지사항 본문은 제외하고 수신합니다.
구독 요청 예제
[
{
"ticket": "trade-announcement-monitor"
},
{
"type": "announcement",
"categories": ["trade"],
"include_body": false
},
{
"format": "DEFAULT"
}
]수신 메시지 예제
{
"type": "announcement",
"event_type": "CREATED",
"uuid": "562593104",
"title": "[거래] 신규 거래 지원 안내 ...",
"category": "trade",
"url": "https://www.upbit.com/service_center/notice?id=562593104&view=share",
"first_listed_at": "2026-07-14T16:36:34+09:00",
"listed_at": "2026-07-14T16:36:34+09:00",
"timestamp": 1752566400123,
"stream_type": "REALTIME"
}공지사항 본문 포함 구독
카테고리 구분 없이 모든 공지사항을 구독하며, include_body를 true로 설정하면 공지 본문까지 함께 수신합니다. ticket은 요청을 식별하기 위한 값으로 원하는 문자열을 직접 지정할 수 있습니다.
구독 요청 예제
[
{
"ticket": "announcement-subscription"
},
{
"type": "announcement",
"include_body": true
},
{
"format": "DEFAULT"
}
]수신 메시지 예제 - 신규 공지 게시
{
"type": "announcement",
"event_type": "CREATED",
"uuid": "562593104",
"title": "[거래] 신규 거래 지원 안내 ...",
"category": "trade",
"url": "https://www.upbit.com/service_center/notice?id=562593104&view=share",
"first_listed_at": "2026-07-14T16:36:34+09:00",
"listed_at": "2026-07-14T16:36:34+09:00",
"timestamp": 1752566400123,
"stream_type": "REALTIME",
"body": "공지사항 본문 ..."
}에러 안내
WebSocket 연결 후 요청에 대한 에러 발생 시, 응답은 다음과 같은 JSON 형식으로 반환됩니다.
{
"error": {
"name": "ERRPR_CODE",
"message": "ERROR_MESSAGE"
}
}반환될 수 있는 주요 에러 코드 목록은 아래와 같습니다.
| error.name | 발생 이유 | 권장 조치 |
|---|---|---|
| INVALID_AUTH | 인증 정보 누락 또는 인증 토큰 검증 실패 | Private WebSocket을 사용하는 경우 올바른 Endpoint에 연결했는지 확인하고, Authorization 헤더에 유효한 인증 토큰이 포함되어 있는지 확인해 주세요. |
| WRONG_FORMAT | 요청 메시지 형식 오류 | 요청 메시지가 WebSocket 요청 형식에 맞게 작성되었는지 확인해 주세요. Object 구성과 각 필드의 타입 및 값을 함께 확인해 주세요. |
| NO_TICKET | ticket 필드 누락 | 요청 메시지에 Ticket Object와 ticket 필드가 포함되어 있는지 확인해 주세요. |
| NO_TYPE | type 필드 누락 | Data Type Object에 type 필드가 포함되어 있는지 확인하고, 구독할 데이터 타입을 지정해 주세요. |
| NO_CODES | codes 필드 누락 | 구독하려는 데이터 타입에서 codes 필드가 필요한지 확인하고, 수신할 페어 코드 목록을 지정해 주세요. |
| INVALID_PARAM | 필수 요청 필드 누락 또는 지원하지 않는 값 요청 | 요청 메시지에 필요한 필드가 포함되어 있는지, 각 필드에 지원하는 값이 지정되었는지 확인해 주세요. |
| Too Many Requests | 요청 한도 초과 | 다음 요청이 가능한 시점까지 대기한 후 다시 요청해 주세요. 요청 한도와 잔여 요청 수 확인 방법은 아래 잔여 요청 수 확인 방법을 참고해 주세요. |
| I'm a teapot | Too Many Requests가 반복되어 일정 시간 요청이 제한된 상태 | 응답에 포함된 제한 시간을 확인하고, 안내된 시간이 지난 후 다시 요청해 주세요. |
요청 수 제한
API는 Rate Limit 그룹으로 묶입니다. 같은 그룹의 API는 초당 한도를 함께 차감합니다. Rate Limit 그룹별 초당 최대 허용 요청 수는 서비스 정책에 따라 공지 후 변경되거나, 서비스 상황에 따라 추가 제한이 발생할 수 있습니다. 자세한 설명은 요청 수 제한(Rate Limits)를 참고해주세요
| Rate Limit 그룹 | 정책 | 적용 단위 |
|---|---|---|
websocket-connect | 초당 최대 5회 | 포켓 |
websocket-message | 초당 최대 5회, 분당 100회 | 커넥션 |