---
title: "연(Year) 캔들 조회"
method: GET
path: "/candles/years"
tags: ["캔들(OHLCV)"]
---

# 연(Year) 캔들 조회

`GET /candles/years`

연 단위 캔들 목록을 조회합니다.

## Query parameters

- `market` string, required — 조회하고자 하는 페어(거래쌍)
- `to` string — 조회 기간의 종료 시각. 지정한 시각 이전 캔들을 조회합니다. 미지정시 요청 시각을 기준으로 최근 캔들이 조회됩니다. ISO 8601 형식의 datetime으로 아래와 같이 요청 할 수 있습니다. 실제 요청 시에는 공백 및 특수문자가 정상적으로 처리되도록 URL 인코딩을 수행해야 합니다. [예시] 2025-06-24T04:56:53Z 2025-06-24 04:56:53 2025-06-24T13:56:53+09:00
- `count` integer — 조회하고자 하는 캔들의 개수. 최대 200개의 캔들 조회를 지원하며, 기본값은 1입니다.

## Response `200`

List of candles

- object[]
  - `market` string, required — 페어(거래쌍)의 코드 [예시] "KRW-BTC"
  - `candle_date_time_utc` string, required — 캔들 구간의 시작 시각 (UTC 기준) [형식] yyyy-MM-dd'T'HH:mm:ss
  - `candle_date_time_kst` string, required — 캔들 구간의 시작 시각 (KST 기준) [형식] yyyy-MM-dd'T'HH:mm:ss
  - `opening_price` number, double, required — 시가. 해당 캔들의 첫 거래 가격입니다.
  - `high_price` number, double, required — 고가. 해당 캔들의 최고 거래 가격입니다.
  - `low_price` number, double, required — 저가. 해당 캔들의 최저 거래 가격입니다.
  - `trade_price` number, double, required — 종가. 해당 페어의 현재 가격입니다.
  - `timestamp` integer, required — 해당 캔들의 마지막 틱이 저장된 시각의 타임스탬프 (ms)
  - `candle_acc_trade_price` number, double, required — 해당 캔들 동안의 누적 거래 금액
  - `candle_acc_trade_volume` number, double, required — 해당 캔들 동안의 누적 거래된 디지털 자산의 수량
  - `first_day_of_period` string, required — 캔들 집계 시작일자 [형식] yyyy-MM-dd

## Other responses

- `400` — error object
- `404` — error object

---

[API](https://skmtc.net/upbit/apis/quotation-api.md) · [All operations](https://skmtc.net/upbit/apis/quotation-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/upbit/quotation-api/revisions/b8bd8b9ed3b5/schema)