WebSocket Usage and Error Guide

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.

TypeEndpointSupported Data Types
Publicwss://{region}-api.upbit.com/websocket/v1ticker, trade, orderbook, candle
Privatewss://{region}-api.upbit.com/websocket/v1/privatemyOrder, 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.

RegionPublic EndpointPrivate Endpoint
Singapore (sg)wss://sg-api.upbit.com/websocket/v1wss://sg-api.upbit.com/websocket/v1/private
Indonesia (id)wss://id-api.upbit.com/websocket/v1wss://id-api.upbit.com/websocket/v1/private
Thailand (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 Authorization header.


Data Types

The data types you can request and subscribe to via Upbit WebSocket are as follows.

Data Type (type)DescriptionSupported Format
tickerReceive current price dataSnapshot, Real-time Stream
tradeReceive trade dataSnapshot, Real-time Stream
orderbookReceive orderbook dataSnapshot, Real-time Stream
candle.{unit}Receive candle dataSnapshot, Real-time Stream
myAssetReceive my asset dataReal-time Stream
myOrderReceive my order dataReal-time Stream
announcementReceive announcement dataReal-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 NameTypeRequiredDescription
ticketStringRequiredA 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 NameTypeRequiredDescription
typeStringRequiredThe data type to receive. For details, refer to the type list below.
codesList[String]ConditionalList of trading pair codes to request or subscribe to. Whether it is required depends on the data type.
categoriesList[String]OptionalList of announcement categories to receive.
Available in Announcement.
include_bodyBooleanOptionalWhether to include the announcement body.
Available in Announcement.
is_only_snapshotBooleanOptionalWhether to request snapshot data only.
Available in Tickers, Trades, Orderbook, and Candles(OHLCV).
is_only_realtimeBooleanOptionalWhether to request real-time stream data only.
Available in Tickers, Trades, Orderbook, and Candles(OHLCV).

Reference by type

typeReference
tickerTickers
tradeTrades
orderbookOrderbook
candle.{unit}Candles(OHLCV)
myAssetMy Asset
myOrderMy Order and Trade
announcementAnnouncement

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 NameTypeRequiredDescription
formatStringOptionalThe 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 PING message. While the connection is active, the server sends an UP status 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.

RegionEndpointMaximum Concurrent Connections per Account
Singaporewss://sg-api.upbit.com/websocket/v1/private5
Indonesiawss://id-api.upbit.com/websocket/v1/private5
Thailandwss://th-api.upbit.com/websocket/v1/private5
  • 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 Requests and the too_many_connections error. 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.nameReason
INVALID_AUTHMissing authentication information or authentication token verification failure
WRONG_FORMATRequest format violation
NO_TICKETMissing ticket field
NO_TYPEMissing type field
NO_CODESMissing codes field
INVALID_PARAMMissing required request parameter or unsupported value requested
TOO_MANY_REQUESTData 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 Codeerror.nameReason
401 Unauthorizedno_authorization_tokenThe Private WebSocket connection request does not include the Authorization header
401 Unauthorizedinvalid_jwtThe Authorization header value is not in a valid Bearer JWT format
401 Unauthorizedinvalid_access_keyThe 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 Requeststoo_many_connectionsPrivate 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."
  }
}