Candles(OHLCV)

Revision History

Version	Date	Changes
v1.2.0	2025-05-12	Addition of `'Candle Data'` minute intervals to WebSocket
v1.1.9	2025-01-20	Addition of `Candle WebSocket`

Candle Real-Time Stream Transmission Guide

Data Transmission Interval

The real-time stream transmission interval for candle data is 1 second.

Data Generation Information

Candles are generated only when trades occur during the given time period and the candle data changes compared to the previous candle. Even if 1 second passes, if no trades occur, no real-time candle data stream is transmitted. Additionally, if the requested candle data for the specified interval has not yet been generated at the time of the request, the data for the previous time interval is sent first.

For example, assuming a 3-minute candle request where the 12:00:00 3-minute candle exists but there have been no trades between 12:03:00 and 12:04:00. If a candle.3m request is sent at 12:04:00, the server returns the 12:00:00–12:03:00 3-minute candle data as snapshot data. When the first trade occurs at 12:04:05, the server immediately creates the 12:03:00 3-minute candle and sends this candle data at the next 1-second interval, 12:04:06.

The same candle_date_time data may be transmitted multiple times.

Due to the nature of real-time candle streams handling requests of various time units, it is difficult to guarantee a perfect transmission interval, and candle data for the same time period may be sent multiple times depending on the trade timing. The most recently received data is the latest; please refer to the candle_date_time field to update the values before use.

Check the proper endpoint based on your region.

The examples in this page is written using Singapore fiat code(SGD). Set the quote currency to match your region. The base_url differs by country/region. Make sure to specify the correct region value for your environment.

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

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

Request Message Format

To request candle data, after establishing the WebSocket connection, you must create a JSON object with the structure below and include it as a Data Type Object in the request message. For the full WebSocket data request message specification including Ticket and Format fields, please refer to the WebSocket Usage Guide document.

Field Name	Type	Description	Required	Default
type	String	Candle type - `candle.1s`: 1-second candle - `candle.1m`: 1-minute candle - `candle.3m`: 3-minute candle - `candle.5m`: 5-minute candle - `candle.10m`: 10-minute candle - `candle.15m`: 15-minute candle - `candle.30m`: 30-minute candle - `candle.60m`: 60-minute candle - `candle.240m`: 240-minute candle	Required
codes	List	List of trading pairs to receive. Must be requested in uppercase.	Required
is_only_snapshot	Boolean	Provide snapshot data only	Optional	`false`
is_only_realtime	Boolean	Provide real-time data only	Optional	`false`

Examples

[
  {
    "ticket": "0e66c0ac-7e13-43ef-91fb-2a87c2956c49"
  },
  {
    "type": "candle.1s",
    "codes": ["SGD-BTC","SGD-ETH"]
  },
  {
    "format": "DEFAULT"
  }
]

[
  {
    "ticket": "0e66c0ac-7e13-43ef-91fb-2a87c2956c49"
  },
  {
    "type": "candle.1s",
    "codes": ["SGD-BTC","SGD-ETH"]
  },
  {
    "format": "SIMPLE_LIST"
  }
]

Subscription Data Specification

The current price snapshot or real-time stream data is returned as follows.

Field Name	Abbreviation	Description	Type	Value
type	ty	Type	String	`candle.1s`: 1-second candle `candle.1m`: 1-minute candle `candle.3m`: 3-minute candle `candle.5m`: 5-minute candle `candle.10m`: 10-minute candle `candle.15m`: 15-minute candle `candle.30m`: 30-minute candle `candle.60m`: 60-minute candle `candle.240m`: 240-minute candle
code	cd	Pair code (e.g., SGD-BTC)	String
candle_date_time_utc	cdttmu	Candle base time (UTC) Format: `yyyy-MM-dd'T'HH:mm:ss`	String
candle_date_time_kst	cdttmk	Candle base time (KST) Format: `yyyy-MM-dd'T'HH:mm:ss`	String
opening_price	op	Opening price	Double
high_price	hp	High price	Double
low_price	lp	Low price	Double
trade_price	tp	Closing price	Double
candle_acc_trade_volume	catv	Accumulated trade volume	Double
candle_acc_trade_price	catp	Accumulated trade amount	Double
timestamp	tms	Timestamp (ms)	Long
stream_type	st	Stream type	String	`SNAPSHOT`: Snapshot `REALTIME`: Real-time

Examples

{
  "type": "candle.1s",
  "code": "SGD-BTC",
  "candle_date_time_utc": "2025-01-02T04:41:51",
  "opening_price": 130155.0000000,
  "high_price": 130155.0000000,
  "low_price": 130155.0000000,
  "trade_price": 130155.0000000,
  "candle_acc_trade_volume": 0.00003473,
  "candle_acc_trade_price": 4.520283150000000,
  "timestamp": 1735792911165,
  "stream_type": "REALTIME"
}
{
  "type": "candle.1s",
  "code": "SGD-ETH",
  "candle_date_time_utc": "2025-01-02T04:42:59",
  "opening_price": 4654.0000000,
  "high_price": 4654.0000000,
  "low_price": 4654.0000000,
  "trade_price": 4654.0000000,
  "candle_acc_trade_volume": 0.00086015,
  "candle_acc_trade_price": 4.003138100000000,
  "timestamp": 1735792979607,
  "stream_type": "REALTIME"
}

[
  {
    "ty": "candle.1s",
    "cd": "SGD-BTC",
    "cdttmu": "2025-06-09T12:13:56",
    "op": 138696.0,
    "hp": 138696.0,
    "lp": 138696.0,
    "tp": 138696.0,
    "catv": 3.093e-05,
    "catp": 4.28986728,
    "tms": 1749471236349,
    "st": "SNAPSHOT"
  },
  {
    "ty": "candle.1s",
    "cd": "SGD-ETH",
    "cdttmu": "2025-06-09T12:11:56",
    "op": 3257.0,
    "hp": 3257.0,
    "lp": 3257.0,
    "tp": 3257.0,
    "catv": 0.0012147,
    "catp": 3.9562779,
    "tms": 1749471116934,
    "st": "SNAPSHOT"
  }
]