WebSocket Usage and Error Guide

Endpoint

The Upbit WebSocket endpoints are as follows. Detailed endpoints vary depending on the category of data you want to query.

Quotation: wss://(sg | id | th)-api.upbit.com/websocket/v1

Exchange: wss://(sg | id | th)-api.upbit.com/websocket/v1/private

Authentication

To subscribe Exchange data over WebSocket, you must connect to the wss://{region}-api.upbit.com/websocket/v1/private endpoint and include authentication credentials. Refer to the Authentication guide to generate a valid JWT token, and include it in the Authorization header of your WebSocket connection request. Bearer authentication is supported, and the header should be formatted as follows:

Authorization: Bearer eyJhb...d8sTw

Rate Limits

Please refer to the Rate Limits document for the Websocket request rate limit policy.

Error Information

When an error occurs after establishing a WebSocket connection and sending a request, the response is returned in the following JSON format.

{
  "error": {
    "name": "ERRPR_CODE",
    "message": "ERROR_MESSAGE"
  }
}

{
  "error": {
    "name": "INVALID_AUTH",
    "message": "Authentication information is invalid."
  }
}

The list of main possible error codes that may be returned is as follows:

Data Types

The data types provided as real-time streams via Upbit WebSocket are as follows.

Data Formats

Data available through WebSocket is divided into two categories: snapshot data and real-time stream data.

• Snapshot refers to receiving information once at the time of the request.
• Real-time stream provide continuously updated information as long as the WebSocket connection is maintained. Depending on the data type, updates may be sent at regular intervals or whenever relevant events occur.

Users can send messages to the server via WebSocket channels to request either snapshot or real-time stream data, and can also request only specific types of data as needed. Please check the supported data types for each channel and use them appropriately for your intended purpose.

Request Messages Structure

A data request message must be sent in the form of a JSON array, containing one or more JSON objects as shown below.

Ticket Object

The first element of the array must be a Ticket Object. The specification for the Ticket Object is as follows.

Data Type Object

Starting from the second element of the array, include one or more data request objects representing the data you wish to query. You can provide two or more objects to request and receive multiple data streams simultaneously. Except for the required type field common to all subscription requests, please refer to the individual Reference documentation for detailed request and response specifications for each data type.

Format Object

As the last element of the array, include the Format Object. Depending on your settings, you can receive data in the standard format, SIMPLE format, or array format. The SIMPLE format returns each field’s key as an abbreviation—for example, the market field is shown as mk. This is useful when you want to minimize data size while receiving a large volume of information. For detailed specifications, refer to the Format Object description below.

Request Example

[
  {"ticket":"3e2c4a9f-f0a7-457f-945e-4b57bde9f1ec"},	
  {"type":"ticker","codes":["SGD-BTC"]}
]

[
  {"ticket":"9a65cd93-8786-4202-9b13-bd90e0c8b64b"},
  {"type":"trade","codes":["SGD-BTC","SGD-ETH"]},
	{"type":"orderbook","codes":["SGD-BTC","SGD-ETH"]},
  {"format":"SIMPLE"}
]

Connection Management

The Upbit WebSocket server supports PING/PONG frames for stable connection management and maintenance.

• If no data is sent or received for 120 seconds, the WebSocket server will close the connection due to idle timeout.
• Clients should periodically send PING frames to the server to prevent automatic disconnection and to check connection status.
• Most WebSocket clients or libraries have built-in functionality to send PING frames to maintain connections. Please verify whether your client supports this feature.
• If implementing PING frames is difficult, you can maintain the connection by sending a simple "PING" message. When the connection is active, the server will send a status message UP every 10 seconds as shown below.

$ telsocket -url wss://sg-api.upbit.com/websocket/v1
Connected!
PING
{"status":"UP"}
{"status":"UP"}
{"status":"UP"}
...

Compression

The Upbit WebSocket server supports Compression to enable faster and more efficient data transmission.

• If your WebSocket client or library supports compression options, you can enable this option to send and receive data in a compressed format.
• Once data transmission is complete, the client or library will automatically decompress the data before presenting it. As a user, you can consume raw data regardless of whether compression is enabled, so no additional implementation for compression handling is required.

Connection and Request Testing

You can quickly test receiving Upbit WebSocket data using a WebSocket client. Below are sample commands for two popular clients: wscat and telsocket. After installing either client, use the following commands to connect and test:

$ npm install -g wscat
$ wscat -c wss://sg-api.upbit.com/websocket/v1
connected (press CTRL+C to quit)

$ telsocket -url wss://(sg|id|th)-api.upbit.com/websocket/v1
Connected!

Once the connection is successfully established, you can send the following request message 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"]}]
{"market":"SGD-BTC","opening_price":8450000.00000000,"high_price":8679000.00000000,"low_price":8445000.00000000,"trade_price":8629000.0,"prev_closing_price":8450000.00000000,"acc_trade_price":105514711074.18726000,"change":"RISE","change_price":179000.00000000,"signed_change_price":179000.00000000,"change_rate":0.0211834320,"signed_change_rate":0.0211834320,"ask_bid":"ASK","trade_volume":0.0105675,"acc_trade_volume":12312.36058857,"trade_date":"20180418","trade_time":"100729","trade_timestamp":1524046049000,"acc_ask_volume":5703.42273172,"acc_bid_volume":6608.93785685,"highest_52_week_price":28885000.00000000,"highest_52_week_date":"2018-01-06","lowest_52_week_price":3286000.00000000,"lowest_52_week_date":"2017-09-15","trade_status":"ACTIVE","market_state":"ACTIVE","market_state_for_ios":"ACTIVE","is_trading_suspended":false,"delisting_date":null,"market_warning":"NONE","timestamp":1524046049766,"acc_trade_price_24h":55330325803.78210000,"acc_trade_volume_24h":6448.96200341}
 {"market":"SGD-BTC","opening_price":8450000.00000000,"high_price":8679000.00000000,"low_price":8445000.00000000,"trade_price":8629000.0,"prev_closing_price":8450000.00000000,"acc_trade_price":105515441503.850220000,"change":"RISE","change_price":179000.00000000,"signed_change_price":179000.00000000,"change_rate":0.0211834320,"signed_change_rate":0.0211834320,"ask_bid":"ASK","trade_volume":0.08464824,"acc_trade_volume":12312.44523681,"trade_date":"20180418","trade_time":"100730","trade_timestamp":1524046050000,"acc_ask_volume":5703.50737996,"acc_bid_volume":6608.93785685,"highest_52_week_price":28885000.00000000,"highest_52_week_date":"2018-01-06","lowest_52_week_price":3286000.00000000,"lowest_52_week_date":"2017-09-15","trade_status":"ACTIVE","market_state":"ACTIVE","market_state_for_ios":"ACTIVE","is_trading_suspended":false,"delisting_date":null,"market_warning":"NONE","timestamp":1524046050758,"acc_trade_price_24h":55330325803.78210000,"acc_trade_volume_24h":6448.96200341}
...

Since you did not explicitly specify to receive only snapshots or only real-time data, the initial snapshot will be sent first, followed by continuous real-time updates.

If you want to receive information for multiple trading pairs simultaneously, list the pair codes separated by commas in the codes field.

Request Example

To receive only the real-time trade data for the SGD-BTC and SGD-ETH markets in a 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"}]
{"mk":"SGD-BTC","tms":1523531768829,"td":"2018-04-12","ttm":"11:16:03","ttms":1523531763000,"tp":7691000.0,"tv":0.00996719,"ab":"BID","pcp":7429000.00000000,"c":"RISE","cp":262000.00000000,"sid":1523531768829000,"st":"SNAPSHOT"}
 {"mk":"SGD-ETH","tms":1523531745481,"td":"2018-04-12","ttm":"11:15:48","ttms":1523531748370,"tp":0.09601999,"tv":0.18711789,"ab":"BID","pcp":0.09618000,"c":"FALL","cp":0.00016001,"sid":15235317454810000,"st":"SNAPSHOT"}
 {"mk":"SGD-BTC","tms":1523531769250,"td":"2018-04-12","ttm":"11:16:04","ttms":1523531764000,"tp":7691000.0,"tv":0.07580113,"ab":"BID","pcp":7429000.00000000,"c":"RISE","cp":262000.00000000,"sid":1523531769250000,"st":"REALTIME"}
 ...

$ 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
      },
      ...
      {
        "ask_price": 162769,
        "bid_price": 142061,
        "ask_size": 0.00310058,
        "bid_size": 0.00339343
      }
    ],
    "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
      },
      {
        "ap": 153750,
        "bp": 152384,
        "as": 0.09,
        "bs": 0.2
      },
      {
        "ap": 153813,
        "bp": 150956,
        "as": 0.2,
        "bs": 0.01627697
...
    "lv": 0
  }
]

Below are additional example requests for your reference to check the request format and usage:

• 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 levels 1 to 3 orderbook for SGD-BTC and levels 1 to 5 orderbook for SGD-ETH pairs [{"ticket":"UNIQUE_TICKET"},{"type":"orderbook","codes":["SGD-BTC.3","SGD-ETH.5"]}]
• Subscribe to trade data for SGD-BTC and real-time orderbook for SGD-ETH pairs [{"ticket":"UNIQUE_TICKET"},{"type":"trade","codes":["SGD-BTC"]},{"type":"orderbook","codes":["SGD-ETH"]}]
• Subscribe to trade data for SGD-BTC, orderbook for SGD-ETH, and ticker data for SGD-SOL pairs [{"ticket":"UNIQUE_TICKET"},{"type":"trade","codes":["SGD-BTC"]},{"type":"orderbook","codes":["SGD-ETH"]},{"type":"ticker","codes":["SGD-SOL"]}]