This is a usage guide for Upbit WebSocket connection and data reception.
Endpoint
Upbit WebSocket endpoints are divided as follows, depending on the data you want to receive.
| Type | Endpoint | Supported Data Types |
|---|---|---|
| Public | wss://{region}-api.upbit.com/websocket/v1 | ticker, trade, orderbook, candle |
| Private | wss://{region}-api.upbit.com/websocket/v1/private | myOrder, myAsset, announcement |
Use the endpoint for your region.The
{region}value differs by country/region. Make sure to specify the correct region value for your environment.
Region Public Endpoint Private Endpoint Singapore (sg) wss://sg-api.upbit.com/websocket/v1wss://sg-api.upbit.com/websocket/v1/privateIndonesia (id) wss://id-api.upbit.com/websocket/v1wss://id-api.upbit.com/websocket/v1/privateThailand (th) wss://th-api.upbit.com/websocket/v1wss://th-api.upbit.com/websocket/v1/private
TLS
Only TLS 1.2 or higher is supported (TLS 1.3 recommended).
Authentication
Authentication is required to connect to the Private WebSocket. Generate a JWT token by referring to the Authentication guide, and include it in the Authorization header in Bearer format. If the authentication information is missing or fails verification, the connection is rejected with HTTP 401 Unauthorized at the connection stage (handshake). For response examples, refer to Connection Stage Errors.
Authorization: Bearer eyJhb...d8sTw
Some WebSocket clients may not support setting headers.Some WebSocket clients may not support setting the custom headers required for authentication. When connecting to the Private WebSocket, check whether your client supports setting the
Authorizationheader.
Data Types
The data types you can request and subscribe to via Upbit WebSocket are as follows.
Data Type (type) | Description | Supported Format |
|---|---|---|
ticker | Receive current price data | Snapshot, Real-time Stream |
trade | Receive trade data | Snapshot, Real-time Stream |
orderbook | Receive orderbook data | Snapshot, Real-time Stream |
candle.{unit} | Receive candle data | Snapshot, Real-time Stream |
myAsset | Receive my asset data | Real-time Stream |
myOrder | Receive my order data | Real-time Stream |
announcement | Receive announcement data | Real-time Stream |
Data Formats
The data formats received via WebSocket are as follows.
- Snapshot refers to receiving information once at the time of the request.
- Real-time stream refers to continuously receiving information while the WebSocket connection is maintained. Depending on the data type, information may be received at regular update intervals or whenever an event occurs.
Request Message Structure and Format
A data request message is a JSON array composed of the following objects.
[
{"ticket": "UNIQUE_TICKET"}, // Ticket Object
{"type": "ticker", "codes": ["SGD-BTC", "SGD-ETH"]}, // Data Type Object
{"type": "orderbook", "codes": ["SGD-BTC"]}, // Data Type Object
{"format": "DEFAULT"} // Format Object (Optional)
]Ticket Object
Enter the Ticket Object as the first element of the array.
| Field Name | Type | Required | Description |
|---|---|---|---|
ticket | String | Required | A unique identifier for the request ticket. Use a string that guarantees uniqueness, such as a UUID. |
Data Type Object
Starting from the second element of the array, enter the data request objects you want to receive. You can enter two or more objects to request and receive multiple data types simultaneously. Except for the type field common to all subscription requests, please refer to the Reference document for each data type for the detailed request object and response specifications.
| Field Name | Type | Required | Description |
|---|---|---|---|
type | String | Required | The data type to receive. For details, refer to the type list below. |
codes | List[String] | Conditional | List of trading pair codes to request or subscribe to. Whether it is required depends on the data type. |
categories | List[String] | Optional | List of announcement categories to receive. Available in Announcement. |
include_body | Boolean | Optional | Whether to include the announcement body. Available in Announcement. |
is_only_snapshot | Boolean | Optional | Whether to request snapshot data only. Available in Tickers, Trades, Orderbook, and Candles(OHLCV). |
is_only_realtime | Boolean | Optional | Whether to request real-time stream data only. Available in Tickers, Trades, Orderbook, and Candles(OHLCV). |
Reference by type
type | Reference |
|---|---|
ticker | Tickers |
trade | Trades |
orderbook | Orderbook |
candle.{unit} | Candles(OHLCV) |
myAsset | My Asset |
myOrder | My Order and Trade |
announcement | Announcement |
Format Object
Optionally enter the Format Object as the last element of the array. The SIMPLE format returns abbreviated field names (e.g., code is returned as cd), which is useful for reducing the size of received data.
| Field Name | Type | Required | Description |
|---|---|---|---|
| format | String | Optional | The data format to receive. Must be one of DEFAULT, SIMPLE, JSON_LIST, or SIMPLE_LIST.· DEFAULT: Default format.· SIMPLE: Simplified format. Each field is returned as an abbreviation.· JSON_LIST: List format.· SIMPLE_LIST: List format with abbreviated field names. |
Connection and Request Testing
Preparing the Client and Connecting
You can quickly test an Upbit WebSocket connection with the wscat or telsocket client. The examples below use the Singapore (sg) endpoint. Replace the region value to match your environment.
$ npm install -g wscat
$ wscat -c wss://sg-api.upbit.com/websocket/v1
connected (press CTRL+C to quit)$ telsocket -url wss://sg-api.upbit.com/websocket/v1
Connected!Sending Your First Request
Send a request message as shown below to subscribe to the real-time ticker stream for the SGD-BTC trading pair.
$ telsocket -url wss://sg-api.upbit.com/websocket/v1
Connected!
[{"ticket":"test"},{"type":"ticker","codes":["SGD-BTC"]}]
{"type":"ticker","code":"SGD-BTC","opening_price":37249,"high_price":37645,"low_price":36732,"trade_price":36929,"prev_closing_price":37235,"acc_trade_price":5530.55648491,"change":"FALL","change_price":306,"signed_change_price":-306,"change_rate":0.0082180744,"signed_change_rate":-0.0082180744,"ask_bid":"ASK","trade_volume":0.00006314,"acc_trade_volume":0.149474,"trade_date":"20230830","trade_time":"082105","trade_timestamp":1693383665811,"acc_ask_volume":0.0197006,"acc_bid_volume":0.1297734,"highest_52_week_price":42710,"highest_52_week_date":"2023-07-06","lowest_52_week_price":21332,"lowest_52_week_date":"2022-11-21","market_state":"ACTIVE","is_trading_suspended":false,"delisting_date":null,"market_warning":"NONE","timestamp":1693383690031,"acc_trade_price_24h":8320.40577449,"acc_trade_volume_24h":0.22569412,"stream_type":"SNAPSHOT"}
...If is_only_snapshot and is_only_realtime are not specified, the snapshot is received first, followed by the continuous real-time stream.
Request and Response Examples by Format
The responses below are examples with some fields and items omitted for explanation.
To receive trade data for the SGD-BTC and SGD-ETH trading pairs in the simplified format (SIMPLE), you can make the request as follows.
$ telsocket -url wss://sg-api.upbit.com/websocket/v1
Connected!
[{"ticket":"test"},{"type":"trade","codes":["SGD-BTC","SGD-ETH"]},{"format":"SIMPLE"}]
{"ty":"trade","cd":"SGD-BTC","tms":1696585056910,"td":"2023-10-06","ttm":"09:37:36","ttms":1696585056846,"tp":37625,"tv":8.428e-05,"ab":"ASK","pcp":37296,"c":"RISE","cp":329,"sid":1696585056846000,"bap":37630,"bas":0.04414411,"bbp":37625,"bbs":0.01202163,"st":"SNAPSHOT"}
...$ telsocket -url wss://sg-api.upbit.com/websocket/v1
Connected!
[{"ticket":"test"},{"type":"orderbook","codes":["SGD-BTC","SGD-ETH","SGD-XRP"]},{"format":"JSON_LIST"}]
[
{
"type": "orderbook",
"code": "SGD-BTC",
"timestamp": 1753973734372,
"total_ask_size": 10.6377063,
"total_bid_size": 0.74153973,
"orderbook_units": [
{
"ask_price": 153487,
"bid_price": 153105,
"ask_size": 0.00011366,
"bid_size": 0.17
}
],
"stream_type": "SNAPSHOT",
"level": 0
}
]$ telsocket -url wss://sg-api.upbit.com/websocket/v1
Connected!
[{"ticket":"test"},{"type":"orderbook","codes":["SGD-BTC","SGD-ETH","SGD-XRP"]},{"format":"SIMPLE_LIST"}]
[
{
"ty": "orderbook",
"cd": "SGD-BTC",
"tms": 1753973734372,
"tas": 10.6377063,
"tbs": 0.74153973,
"obu": [
{
"ap": 153487,
"bp": 153105,
"as": 0.00011366,
"bs": 0.17
}
],
"lv": 0
}
]Other Request Examples
-
Subscribe to real-time trade streams for SGD-BTC and SGD-ETH pairs
[{"ticket":"UNIQUE_TICKET"},{"type":"trade","codes":["SGD-BTC","SGD-ETH"]}] -
Subscribe to real-time orderbook streams for SGD-BTC and SGD-ETH pairs
[{"ticket":"UNIQUE_TICKET"},{"type":"orderbook","codes":["SGD-BTC","SGD-ETH"]}] -
Subscribe to real-time orderbook streams with 5 orderbook units for SGD-BTC and 15 orderbook units for SGD-ETH
[{"ticket":"UNIQUE_TICKET"},{"type":"orderbook","codes":["SGD-BTC.5","SGD-ETH.15"]}] -
Subscribe to trade data for SGD-BTC and the real-time orderbook stream for SGD-ETH
[{"ticket":"UNIQUE_TICKET"},{"type":"trade","codes":["SGD-BTC"]},{"type":"orderbook","codes":["SGD-ETH"]}] -
Subscribe to trade for SGD-BTC, orderbook for SGD-ETH, and ticker for SGD-XRP streams
[{"ticket":"UNIQUE_TICKET"},{"type":"trade","codes":["SGD-BTC"]},{"type":"orderbook","codes":["SGD-ETH"]},{"type":"ticker", "codes":["SGD-XRP"]}] -
Subscribe to the real-time announcement stream
[{"ticket":"UNIQUE_TICKET"},{"type":"announcement"}] -
Subscribe to the real-time announcement stream for the trading and wallet categories, including the announcement body
[{"ticket":"UNIQUE_TICKET"},{"type":"announcement","categories":["trading","wallet"],"include_body":true}]
Connection Management
Keeping the Connection Alive
The Upbit WebSocket server supports PING/PONG Frames for stable connection management and maintenance.
- By default, the WebSocket server closes the connection due to idle timeout if no data is sent or received for 120 seconds.
- Clients can periodically send PING Frames to the server to prevent automatic disconnection and check the connection status.
- If implementing PING Frames separately is difficult, you can keep the connection alive by sending a
PINGmessage. While the connection is active, the server sends anUPstatus message to the client every 10 seconds, as shown below.
$ telsocket -url wss://sg-api.upbit.com/websocket/v1
Connected!
PING
{"status":"UP"}
{"status":"UP"}
{"status":"UP"}
...Private WebSocket Concurrent Connection Limit
In addition to rate limits, a concurrent connection limit per account is applied to the Private WebSocket. The Public WebSocket (wss://{region}-api.upbit.com/websocket/v1) is not subject to this limit.
| Region | Endpoint | Maximum Concurrent Connections per Account |
|---|---|---|
| Singapore | wss://sg-api.upbit.com/websocket/v1/private | 5 |
| Indonesia | wss://id-api.upbit.com/websocket/v1/private | 5 |
| Thailand | wss://th-api.upbit.com/websocket/v1/private | 5 |
- The number of concurrent connections is counted per account. Connections made with different API Keys issued under the same account are added together.
- Close unused connections, and subscribe to multiple data types supported by the same endpoint through a single connection.
- New connection requests exceeding the limit are rejected with HTTP
429 Too Many Requestsand thetoo_many_connectionserror. For response examples, refer to Connection Stage Errors. - The concurrent connection limit may change, or additional restrictions may be applied, depending on service conditions.
Compression
The Upbit WebSocket server supports Compression for faster and more efficient data transmission.
- If your WebSocket client or library supports compression options, you can enable them to send and receive data in a compressed format.
- Decompression is handled by the client or library, so no separate implementation is required.
Rate Limits
For the WebSocket rate limit policy, refer to the Rate Limits document.
Error Information
When an error occurs for a request after the WebSocket connection is established, the response is returned in the following JSON format.
{
"error": {
"name": "ERROR_NAME",
"message": "ERROR_MESSAGE"
}
}{
"error": {
"name": "INVALID_AUTH",
"message": "Authentication information is invalid."
}
}The main error.name values that may be returned are as follows.
error.name | Reason |
|---|---|
INVALID_AUTH | Missing authentication information or authentication token verification failure |
WRONG_FORMAT | Request format violation |
NO_TICKET | Missing ticket field |
NO_TYPE | Missing type field |
NO_CODES | Missing codes field |
INVALID_PARAM | Missing required request parameter or unsupported value requested |
TOO_MANY_REQUEST | Data request message limit exceeded |
The message value in error responses may change, so please handle errors based on the error.name value. If request validation fails or the request limit is exceeded, the server sends an error response and then closes the WebSocket connection.
Connection Stage Errors
The errors below are returned as the HTTP response body at the connection stage (handshake). Therefore, WebSocket clients or libraries may treat them as connection failures rather than messages.
| HTTP Status Code | error.name | Reason |
|---|---|---|
401 Unauthorized | no_authorization_token | The Private WebSocket connection request does not include the Authorization header |
401 Unauthorized | invalid_jwt | The Authorization header value is not in a valid Bearer JWT format |
401 Unauthorized | invalid_access_key | The JWT signature is invalid, or the access_key or nonce claim is missing |
429 Too Many Requests | — | WebSocket connection request limit (5 per second) exceeded. Refer to Rate Limits |
429 Too Many Requests | too_many_connections | Private WebSocket concurrent connection limit exceeded. Refer to Private WebSocket Concurrent Connection Limit |
{
"error": {
"name": "too_many_connections",
"message": "The maximum number of concurrent Private WebSocket connections has been exceeded."
}
}