quotation.yaml

openapi: "3.1.0"
info:
  title: Upbit Quotation API
  description: |
    업비트 시세 조회(Quotation) API 명세.
    인증 불필요한 공개 API입니다.

    ## 공통 사항
    - TLS 1.2 이상 필요 (1.3 권장)
    - Content-Type: application/json; charset=utf-8
    - Quotation API는 gzip 압축을 지원합니다 (Accept-Encoding: gzip)
    - 모든 Rate Limit은 IP 단위로 측정됩니다
    - 응답 헤더 Remaining-Req로 잔여 요청 횟수를 확인할 수 있습니다
      (형식: "group=default; min=1800; sec=29")
  version: "1.6.1"
  contact:
    name: Upbit Open API
    url: https://docs.upbit.com

servers:
  - url: https://api.upbit.com
    description: Upbit Production

tags:
  - name: ticker
    description: 현재가 조회
  - name: candle
    description: 캔들(봉) 조회
  - name: orderbook
    description: 호가 조회
  - name: trade
    description: 체결 내역 조회
  - name: market
    description: 마켓(페어) 정보 조회

# ─────────────────────────── paths ───────────────────────────

paths:

  # ── Ticker ──

  /v1/ticker/all:
    get:
      operationId: listQuoteTickers
      summary: 마켓 단위 현재가 조회
      description: |
        지정한 마켓(호가 자산) 내 모든 페어들의 현재가 정보를 조회합니다.

        가격 변동 지표(change, change_price, change_rate, signed_change_price, signed_change_rate)는
        전일 종가를 기준으로 산출합니다.
      tags: [ticker]
      x-rate-limit:
        group: Quotationticker
        max_per_sec: 10
        unit: ip
      parameters:
        - name: quote_currencies
          in: query
          required: true
          description: |
            조회하고자 하는 마켓의 통화 코드 목록.
            2개 이상의 마켓에 대해 조회하고자 하는 경우 쉼표(,)로 구분된 문자열 형식으로 요청합니다.
          schema:
            type: string
          example: "KRW,BTC"
      responses:
        "200":
          description: 마켓 단위 현재가 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Ticker"
        "400":
          $ref: "#/components/responses/BadRequest"

  /v1/ticker:
    get:
      operationId: listTickers
      summary: 페어 단위 현재가 조회
      description: |
        지정한 페어의 현재가를 조회합니다.
        요청 시점 기준으로 해당 페어의 티커 스냅샷이 반환됩니다.

        가격 변동 지표(change, change_price, change_rate, signed_change_price, signed_change_rate)는
        전일 종가를 기준으로 산출합니다.
      tags: [ticker]
      x-rate-limit:
        group: Quotationticker
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketsParam"
      responses:
        "200":
          description: 페어 단위 현재가 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Ticker"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Market ──

  /v1/market/all:
    get:
      operationId: listTradingPairs
      summary: 페어 목록 조회
      description: 업비트에서 지원하는 모든 페어 목록을 조회합니다.
      tags: [market]
      x-rate-limit:
        group: Quotationmarket
        max_per_sec: 10
        unit: ip
      parameters:
        - name: is_details
          in: query
          required: false
          description: |
            상세 정보를 포함한 조회 여부.
            true로 지정하여 유의종목 지정 여부, 주의종목 지정 여부와 같은
            상세 정보를 응답에 포함할 수 있습니다. 기본값은 false입니다.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: 페어 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TradingPair"
        "400":
          $ref: "#/components/responses/BadRequest"

  # ── Candles ──

  /v1/candles/minutes/{unit}:
    get:
      operationId: listCandlesMinutes
      summary: 분(Minute) 캔들 조회
      description: |
        분 단위 캔들 목록을 조회합니다.
        1, 3, 5, 10, 15, 30, 60, 240분 단위로 캔들 너비를 조정할 수 있습니다.

        캔들은 해당 시간대에 체결이 발생한 경우에만 생성됩니다.
        체결이 발생하지 않은 시간대는 응답에 포함되지 않습니다.
      tags: [candle]
      x-rate-limit:
        group: Quotationcandle
        max_per_sec: 10
        unit: ip
      parameters:
        - name: unit
          in: path
          required: true
          description: "분(Minute) 캔들 단위. 최대 240분(4시간) 캔들까지 조회할 수 있습니다."
          schema:
            type: integer
            enum: [1, 3, 5, 10, 15, 30, 60, 240]
        - $ref: "#/components/parameters/MarketParam"
        - $ref: "#/components/parameters/ToParam"
        - $ref: "#/components/parameters/CountParam"
      responses:
        "200":
          description: 분 캔들 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CandleMinute"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/candles/seconds:
    get:
      operationId: listCandlesSeconds
      summary: 초(Second) 캔들 조회
      description: |
        초 단위 캔들 목록을 조회합니다.

        초 캔들(초봉) 조회 지원 기간은 최대 3개월입니다.
        요청 시점을 기준으로 최근 3개월 이내의 데이터만 제공합니다.
        조회 가능 기간을 초과한 경우 빈 리스트가 반환됩니다.

        캔들은 해당 시간대에 체결이 발생한 경우에만 생성됩니다.
      tags: [candle]
      x-rate-limit:
        group: Quotationcandle
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketParam"
        - $ref: "#/components/parameters/ToParam"
        - $ref: "#/components/parameters/CountParam"
      responses:
        "200":
          description: 초 캔들 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CandleSecond"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/candles/days:
    get:
      operationId: listCandlesDays
      summary: 일(Day) 캔들 조회
      description: |
        일 단위 캔들 목록을 조회합니다.

        converting_price_unit 파라미터를 지정하여 원화 마켓이 아닌 다른 마켓의
        일 캔들 조회시 종가를 원화로 환산하여 조회할 수 있습니다.

        캔들은 해당 시간대에 체결이 발생한 경우에만 생성됩니다.
      tags: [candle]
      x-rate-limit:
        group: Quotationcandle
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketParam"
        - $ref: "#/components/parameters/ToParam"
        - $ref: "#/components/parameters/CountParam"
        - name: converting_price_unit
          in: query
          required: false
          description: |
            종가 환산 통화. 종가를 특정 통화로 환산하고자 하는 경우 선택적으로 지정할 수 있습니다.
            사용시 응답에 converted_trade_price 필드가 추가로 반환됩니다.
            현재 원화(KRW)로의 변환만 지원합니다.
          schema:
            type: string
          example: "KRW"
      responses:
        "200":
          description: 일 캔들 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CandleDay"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/candles/weeks:
    get:
      operationId: listCandlesWeeks
      summary: 주(Week) 캔들 조회
      description: 주 단위 캔들 목록을 조회합니다.
      tags: [candle]
      x-rate-limit:
        group: Quotationcandle
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketParam"
        - $ref: "#/components/parameters/ToParam"
        - $ref: "#/components/parameters/CountParam"
      responses:
        "200":
          description: 주 캔들 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CandlePeriod"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/candles/months:
    get:
      operationId: listCandlesMonths
      summary: 월(Month) 캔들 조회
      description: 월 단위 캔들 목록을 조회합니다.
      tags: [candle]
      x-rate-limit:
        group: Quotationcandle
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketParam"
        - $ref: "#/components/parameters/ToParam"
        - $ref: "#/components/parameters/CountParam"
      responses:
        "200":
          description: 월 캔들 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CandlePeriod"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/candles/years:
    get:
      operationId: listCandlesYears
      summary: 연(Year) 캔들 조회
      description: 연 단위 캔들 목록을 조회합니다.
      tags: [candle]
      x-rate-limit:
        group: Quotationcandle
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketParam"
        - $ref: "#/components/parameters/ToParam"
        - $ref: "#/components/parameters/CountParam"
      responses:
        "200":
          description: 연 캔들 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CandlePeriod"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Orderbook ──

  /v1/orderbook:
    get:
      operationId: listOrderbooks
      summary: 호가 조회
      description: |
        지정한 종목들의 실시간 호가(Orderbook) 정보를 조회합니다.

        호가 모아보기(level)는 원화마켓(KRW)에서만 지원하는 기능으로,
        지정한 단위로 ask/bid price와 size를 모아(group) 조회할 수 있습니다.
        종목별 호가 단위에 따라 지원하는 모아보기 단위가 다릅니다.
        미지원 단위를 지정하는 경우 빈 배열이 반환됩니다.
      tags: [orderbook]
      x-rate-limit:
        group: Quotationorderbook
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketsParam"
        - name: level
          in: query
          required: false
          description: |
            호가 모아보기 단위. 원화마켓(KRW)에서만 지원합니다.
            숫자 형식의 String으로 요청합니다. 0은 기본 호가단위입니다.
          schema:
            type: string
            default: "0"
          example: "100000"
        - name: count
          in: query
          required: false
          description: |
            조회하고자 하는 호가 쌍의 개수.
            최고 매수 호가 - 최저 매도 호가의 쌍을 기준으로 반환됩니다. 최대 30.
          schema:
            type: integer
            default: 30
            maximum: 30
      responses:
        "200":
          description: 호가 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Orderbook"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/orderbook/instruments:
    get:
      operationId: listOrderbookInstruments
      summary: 호가 정책 조회
      description: 지정한 페어들의 호가 단위(tick_size)와 호가 모아보기 단위(supported_levels) 정보를 조회합니다.
      tags: [orderbook]
      x-rate-limit:
        group: Quotationorderbook
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketsParam"
      responses:
        "200":
          description: 호가 정책 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/OrderbookInstrument"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Trade ──

  /v1/trades/ticks:
    get:
      operationId: listRecentTrades
      summary: 최근 체결 내역 조회
      description: |
        지정한 페어의 최근 체결 목록을 조회합니다.
        최대 7일의 조회 기간을 지원합니다. 일자 구분은 UTC를 기준으로 합니다.
      tags: [trade]
      x-rate-limit:
        group: Quotationtrade
        max_per_sec: 10
        unit: ip
      parameters:
        - $ref: "#/components/parameters/MarketParam"
        - name: to
          in: query
          required: false
          description: |
            조회 대상 일자 내 조회 기간의 종료 시각(UTC).
            HHmmss 또는 HH:mm:ss 형식으로 입력합니다.
            체결 목록이 지정한 시간부터 시간 역순으로 반환됩니다.
          schema:
            type: string
          example: "130000"
        - name: count
          in: query
          required: false
          description: "조회하고자 하는 체결 내역의 개수. 최대 500개, 기본값 1."
          schema:
            type: integer
            default: 1
            maximum: 500
        - name: cursor
          in: query
          required: false
          description: |
            Pagination을 위한 조회 범위 지정용 커서.
            응답에 포함된 체결의 sequential_id 값을 입력하여
            해당 체결 직전 데이터부터 이어서 조회할 수 있습니다.
          schema:
            type: string
        - name: days_ago
          in: query
          required: false
          description: |
            체결 내역 조회 대상 일자와 요청 시점과의 일 단위 offset.
            1 이상 7 이하의 정수. 빈 값이면 요청 당일 체결 목록 반환.
          schema:
            type: integer
            minimum: 1
            maximum: 7
      responses:
        "200":
          description: 최근 체결 내역 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Trade"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

# ─────────────────────────── components ───────────────────────────

components:

  # ── Parameters ──

  parameters:
    MarketParam:
      name: market
      in: query
      required: true
      description: "조회하고자 하는 페어(거래쌍)"
      schema:
        type: string
      example: "KRW-BTC"

    MarketsParam:
      name: markets
      in: query
      required: true
      description: |
        조회하고자 하는 페어(거래쌍) 목록.
        2개 이상의 페어는 쉼표(,)로 구분된 문자열 형식으로 요청합니다.
      schema:
        type: string
      example: "KRW-BTC,KRW-ETH,BTC-ETH"

    ToParam:
      name: to
      in: query
      required: false
      description: |
        조회 기간의 종료 시각. 지정한 시각 이전 캔들을 조회합니다.
        미지정시 요청 시각 기준 최근 캔들이 조회됩니다.
        ISO 8601 형식의 datetime.
      schema:
        type: string
      example: "2025-06-24T04:56:53Z"

    CountParam:
      name: count
      in: query
      required: false
      description: "조회하고자 하는 캔들의 개수. 최대 200개, 기본값 1."
      schema:
        type: integer
        default: 1
        maximum: 200

  # ── Responses ──

  responses:
    BadRequest:
      description: 잘못된 요청 파라미터
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            invalidParameter:
              summary: 파라미터 오류
              value:
                error:
                  name: 400
                  message: "Invalid parameter. Check the given value!"
            typeMismatch:
              summary: 파라미터 타입 오류
              value:
                error:
                  name: 400
                  message: "Type mismatch error. Check the parameters type!"
            missingParameter:
              summary: 필수 파라미터 누락
              value:
                error:
                  name: 400
                  message: "Missing request parameter error. Check the required parameters!"

    NotFound:
      description: 리소스를 찾을 수 없음
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              name: 404
              message: "Code not found"

  # ── Schemas ──

  schemas:

    # ── Error ──

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [name, message]
          properties:
            name:
              description: 에러 코드 또는 에러명
              oneOf:
                - type: integer
                - type: string
            message:
              type: string
              description: 에러 메세지

    # ── Ticker ──

    Ticker:
      type: object
      required:
        - market
        - trade_date
        - trade_time
        - trade_date_kst
        - trade_time_kst
        - trade_timestamp
        - opening_price
        - high_price
        - low_price
        - trade_price
        - prev_closing_price
        - change
        - change_price
        - change_rate
        - signed_change_price
        - signed_change_rate
        - trade_volume
        - acc_trade_price
        - acc_trade_price_24h
        - acc_trade_volume
        - acc_trade_volume_24h
        - highest_52_week_price
        - highest_52_week_date
        - lowest_52_week_price
        - lowest_52_week_date
        - timestamp
      properties:
        market:
          type: string
          description: "페어(거래쌍)의 코드"
          example: "KRW-BTC"
        trade_date:
          type: string
          description: "최근 체결 일자 (UTC 기준) [형식] yyyyMMdd"
          example: "20250704"
        trade_time:
          type: string
          description: "최근 체결 시각 (UTC 기준) [형식] HHmmss"
          example: "051400"
        trade_date_kst:
          type: string
          description: "최근 체결 일자 (KST 기준) [형식] yyyyMMdd"
          example: "20250704"
        trade_time_kst:
          type: string
          description: "최근 체결 시각 (KST 기준) [형식] HHmmss"
          example: "141400"
        trade_timestamp:
          type: integer
          format: int64
          description: "현재가 정보가 반영된 시각의 타임스탬프(ms)"
          example: 1751606040365
        opening_price:
          type: number
          format: double
          description: "시가. 해당 페어의 첫 거래 가격"
          example: 148737000
        high_price:
          type: number
          format: double
          description: "고가. 해당 페어의 최고 거래 가격"
          example: 149360000
        low_price:
          type: number
          format: double
          description: "저가. 해당 페어의 최저 거래 가격"
          example: 148288000
        trade_price:
          type: number
          format: double
          description: "종가. 해당 페어의 현재 가격"
          example: 148601000
        prev_closing_price:
          type: number
          format: double
          description: "전일 종가 (UTC 0시 기준)"
          example: 148737000
        change:
          type: string
          enum: [EVEN, RISE, FALL]
          description: "가격 변동 상태. EVEN: 보합, RISE: 상승, FALL: 하락"
          example: "FALL"
        change_price:
          type: number
          format: double
          description: "전일 종가 대비 가격 변화(절대값)"
          example: 136000
        change_rate:
          type: number
          format: double
          description: "전일 종가 대비 가격 변화율(절대값). 0.015 = 1.5%"
          example: 0.0009143656
        signed_change_price:
          type: number
          format: double
          description: "전일 종가 대비 가격 변화. 양수(+): 상승, 음수(-): 하락"
          example: -136000
        signed_change_rate:
          type: number
          format: double
          description: "전일 종가 대비 가격 변화율. 양수(+): 상승, 음수(-): 하락"
          example: -0.0009143656
        trade_volume:
          type: number
          format: double
          description: "최근 거래 수량"
          example: 0.00016823
        acc_trade_price:
          type: number
          format: double
          description: "누적 거래 금액 (UTC 0시 기준)"
          example: 31615925234.05438
        acc_trade_price_24h:
          type: number
          format: double
          description: "24시간 누적 거래 금액"
          example: 178448329314.96686
        acc_trade_volume:
          type: number
          format: double
          description: "누적 거래량 (UTC 0시 기준)"
          example: 212.38911576
        acc_trade_volume_24h:
          type: number
          format: double
          description: "24시간 누적 거래량"
          example: 1198.26954807
        highest_52_week_price:
          type: number
          format: double
          description: "52주 신고가"
          example: 163325000
        highest_52_week_date:
          type: string
          description: "52주 신고가 달성일 [형식] yyyy-MM-dd"
          example: "2025-01-20"
        lowest_52_week_price:
          type: number
          format: double
          description: "52주 신저가"
          example: 72100000
        lowest_52_week_date:
          type: string
          description: "52주 신저가 달성일 [형식] yyyy-MM-dd"
          example: "2024-08-05"
        timestamp:
          type: integer
          format: int64
          description: "현재가 정보가 반영된 시각의 타임스탬프(ms)"
          example: 1751606040403

    # ── Trading Pair ──

    TradingPair:
      type: object
      required: [market, korean_name, english_name]
      properties:
        market:
          type: string
          description: "페어(거래쌍)의 코드"
          example: "KRW-BTC"
        korean_name:
          type: string
          description: "해당 디지털 자산의 한글명"
          example: "비트코인"
        english_name:
          type: string
          description: "해당 디지털 자산의 영문명"
          example: "Bitcoin"
        market_event:
          type: object
          description: "종목 경보 정보 (is_details=true인 경우 포함)"
          properties:
            warning:
              type: boolean
              description: "유의 종목 지정 여부"
            caution:
              type: object
              description: "주의 종목 지정 여부"
              properties:
                PRICE_FLUCTUATIONS:
                  type: boolean
                TRADING_VOLUME_SOARING:
                  type: boolean
                DEPOSIT_AMOUNT_SOARING:
                  type: boolean
                GLOBAL_PRICE_DIFFERENCES:
                  type: boolean
                CONCENTRATION_OF_SMALL_ACCOUNTS:
                  type: boolean

    # ── Candles ──

    CandleBase:
      type: object
      required:
        - market
        - candle_date_time_utc
        - candle_date_time_kst
        - opening_price
        - high_price
        - low_price
        - trade_price
        - timestamp
        - candle_acc_trade_price
        - candle_acc_trade_volume
      properties:
        market:
          type: string
          description: "페어(거래쌍)의 코드"
          example: "KRW-BTC"
        candle_date_time_utc:
          type: string
          description: "캔들 구간의 시작 시각 (UTC 기준) [형식] yyyy-MM-dd'T'HH:mm:ss"
          example: "2025-07-01T12:00:00"
        candle_date_time_kst:
          type: string
          description: "캔들 구간의 시작 시각 (KST 기준) [형식] yyyy-MM-dd'T'HH:mm:ss"
          example: "2025-07-01T21:00:00"
        opening_price:
          type: number
          format: double
          description: "시가. 해당 캔들의 첫 거래 가격"
          example: 145831000
        high_price:
          type: number
          format: double
          description: "고가. 해당 캔들의 최고 거래 가격"
          example: 145831000
        low_price:
          type: number
          format: double
          description: "저가. 해당 캔들의 최저 거래 가격"
          example: 145752000
        trade_price:
          type: number
          format: double
          description: "종가. 해당 페어의 현재 가격"
          example: 145759000
        timestamp:
          type: integer
          format: int64
          description: "해당 캔들의 마지막 틱이 저장된 시각의 타임스탬프(ms)"
          example: 1751327999833
        candle_acc_trade_price:
          type: number
          format: double
          description: "해당 캔들 동안의 누적 거래 금액"
          example: 4022470467.03403
        candle_acc_trade_volume:
          type: number
          format: double
          description: "해당 캔들 동안의 누적 거래된 디지털 자산의 수량"
          example: 27.58904602

    CandleMinute:
      description: 분(Minute) 캔들
      allOf:
        - $ref: "#/components/schemas/CandleBase"
        - type: object
          required: [unit]
          properties:
            unit:
              type: integer
              enum: [1, 3, 5, 10, 15, 30, 60, 240]
              description: "캔들 집계 시간 단위(분)"
              example: 1

    CandleSecond:
      description: 초(Second) 캔들. 요청 시점 기준 최대 3개월 이내 데이터만 제공.
      allOf:
        - $ref: "#/components/schemas/CandleBase"

    CandleDay:
      description: 일(Day) 캔들
      allOf:
        - $ref: "#/components/schemas/CandleBase"
        - type: object
          required: [prev_closing_price, change_price, change_rate]
          properties:
            prev_closing_price:
              type: number
              format: double
              description: "전일 종가 (UTC 0시 기준)"
              example: 147996000
            change_price:
              type: number
              format: double
              description: "전일 종가 대비 가격 변화. 양수(+): 상승, 음수(-): 하락, 0: 변화 없음"
              example: -2237000
            change_rate:
              type: number
              format: double
              description: "전일 종가 대비 가격 변화율. 0.015 = 1.5%"
              example: -0.0151152734
            converted_trade_price:
              type: number
              format: double
              description: |
                종가 환산 가격. converting_price_unit 파라미터 지정시에만 반환됩니다.
                현재는 원화(KRW)로의 변환만 지원합니다.

    CandlePeriod:
      description: 주(Week)/월(Month)/연(Year) 캔들
      allOf:
        - $ref: "#/components/schemas/CandleBase"
        - type: object
          required: [first_day_of_period]
          properties:
            first_day_of_period:
              type: string
              description: "캔들 집계 기간의 시작일 [형식] yyyy-MM-dd"
              example: "2025-06-30"

    # ── Orderbook ──

    Orderbook:
      type: object
      required:
        - market
        - timestamp
        - total_ask_size
        - total_bid_size
        - orderbook_units
        - level
      properties:
        market:
          type: string
          description: "페어(거래쌍)의 코드"
          example: "KRW-BTC"
        timestamp:
          type: integer
          format: int64
          description: "조회 요청 시각의 타임스탬프(ms)"
          example: 1751606867762
        total_ask_size:
          type: number
          format: double
          description: "현재 호가의 전체 매도 잔량 합계"
          example: 10.37591054
        total_bid_size:
          type: number
          format: double
          description: "현재 호가의 전체 매수 잔량 합계"
          example: 9.49577219
        orderbook_units:
          type: array
          description: "호가 정보. 차례대로 1호가, 2호가 ... 30호가"
          items:
            $ref: "#/components/schemas/OrderbookUnit"
        level:
          type: number
          format: double
          description: "해당 호가가 적용된 가격 단위"
          example: 10000

    OrderbookUnit:
      type: object
      required: [ask_price, bid_price, ask_size, bid_size]
      properties:
        ask_price:
          type: number
          format: double
          description: "매도 호가"
          example: 148520000
        bid_price:
          type: number
          format: double
          description: "매수 호가"
          example: 148490000
        ask_size:
          type: number
          format: double
          description: "매도 잔량"
          example: 0.0134662
        bid_size:
          type: number
          format: double
          description: "매수 잔량"
          example: 0.04296774

    OrderbookInstrument:
      type: object
      required: [market, quote_currency, tick_size, supported_levels]
      properties:
        market:
          type: string
          description: "페어(거래쌍)의 코드"
          example: "KRW-BTC"
        quote_currency:
          type: string
          description: "해당 페어의 마켓 통화 코드"
          example: "KRW"
        tick_size:
          type: string
          description: "해당 페어에 적용되는 호가 단위"
          example: "1000"
        supported_levels:
          type: array
          description: |
            해당 페어에서 지원하는 호가 모아보기 단위.
            0: 기본 호가단위. 호가 모아보기는 원화마켓(KRW)에서만 지원합니다.
          items:
            type: string
          example: ["0", "10000", "100000", "1000000", "10000000", "100000000"]

    # ── Trade ──

    Trade:
      type: object
      required:
        - market
        - trade_date_utc
        - trade_time_utc
        - timestamp
        - trade_price
        - trade_volume
        - prev_closing_price
        - change_price
        - ask_bid
        - sequential_id
      properties:
        market:
          type: string
          description: "페어(거래쌍)의 코드"
          example: "KRW-BTC"
        trade_date_utc:
          type: string
          description: "체결 일자 (UTC 기준) [형식] yyyy-MM-dd"
          example: "2025-06-27"
        trade_time_utc:
          type: string
          description: "체결 시각 (UTC 기준) [형식] HH:mm:ss"
          example: "23:59:59"
        timestamp:
          type: integer
          format: int64
          description: "체결 시각의 밀리초단위 타임스탬프"
          example: 1751068799336
        trade_price:
          type: number
          format: double
          description: "최근 체결 가격"
          example: 147058000
        trade_volume:
          type: number
          format: double
          description: "최근 거래 수량"
          example: 0.00006043
        prev_closing_price:
          type: number
          format: double
          description: "전일 종가 (UTC 0시 기준)"
          example: 146852000
        change_price:
          type: number
          format: double
          description: "전일 종가 대비 가격 변화. 양수(+): 상승, 음수(-): 하락, 0: 변화 없음"
          example: 206000
        ask_bid:
          type: string
          enum: [ASK, BID]
          description: "매수/매도 주문 구분. ASK: 매도, BID: 매수"
          example: "BID"
        sequential_id:
          type: integer
          description: "체결의 유일 식별자. 체결 순서를 보장하지 않습니다."
          example: 17510687993360000