@upbit-official/upbit-sdk 0.9.0

package/src/resources/candles.ts

@@ -0,0 +1,392 @@
+
+import { APIResource } from '../core/resource';
+import * as CandlesAPI from './candles';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Candles extends APIResource {
+  /**
+   * List Day Candles
+   *
+   * GET /v1/candles/days
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-candles-days
+   * - docs(global): https://global-docs.upbit.com/reference/list-candles-days
+   *
+   * @example
+   * ```ts
+   * const response = await client.candles.listDays({
+   *   market: 'KRW-BTC',
+   * });
+   * ```
+   */
+  listDays(query: CandleListDaysParams, options?: RequestOptions): APIPromise<CandleListDaysResponse> {
+    return this._client.get('/v1/candles/days', { query, ...options, __security: {} });
+  }
+
+  /**
+   * List Minute Candles
+   *
+   * GET /v1/candles/minutes/{unit}
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-candles-minutes
+   * - docs(global): https://global-docs.upbit.com/reference/list-candles-minutes
+   *
+   * @example
+   * ```ts
+   * const candles = await client.candles.listMinutes(15, {
+   *   market: 'KRW-BTC',
+   * });
+   * ```
+   */
+  listMinutes(
+    unit: 1 | 3 | 5 | 10 | 15 | 30 | 60 | 240,
+    query: CandleListMinutesParams,
+    options?: RequestOptions,
+  ): APIPromise<CandleListMinutesResponse> {
+    return this._client.get(path`/v1/candles/minutes/${unit}`, { query, ...options, __security: {} });
+  }
+
+  /**
+   * List Month Candles
+   *
+   * GET /v1/candles/months
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-candles-months
+   * - docs(global): https://global-docs.upbit.com/reference/list-candles-months
+   *
+   * @example
+   * ```ts
+   * const candlePeriods = await client.candles.listMonths({
+   *   market: 'KRW-BTC',
+   * });
+   * ```
+   */
+  listMonths(query: CandleListMonthsParams, options?: RequestOptions): APIPromise<CandleListMonthsResponse> {
+    return this._client.get('/v1/candles/months', { query, ...options, __security: {} });
+  }
+
+  /**
+   * List Second Candles
+   *
+   * GET /v1/candles/seconds
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-candles-seconds
+   * - docs(global): https://global-docs.upbit.com/reference/list-candles-seconds
+   *
+   * @example
+   * ```ts
+   * const candles = await client.candles.listSeconds({
+   *   market: 'KRW-BTC',
+   * });
+   * ```
+   */
+  listSeconds(
+    query: CandleListSecondsParams,
+    options?: RequestOptions,
+  ): APIPromise<CandleListSecondsResponse> {
+    return this._client.get('/v1/candles/seconds', { query, ...options, __security: {} });
+  }
+
+  /**
+   * List Week Candles
+   *
+   * GET /v1/candles/weeks
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-candles-weeks
+   * - docs(global): https://global-docs.upbit.com/reference/list-candles-weeks
+   *
+   * @example
+   * ```ts
+   * const candlePeriods = await client.candles.listWeeks({
+   *   market: 'KRW-BTC',
+   * });
+   * ```
+   */
+  listWeeks(query: CandleListWeeksParams, options?: RequestOptions): APIPromise<CandleListWeeksResponse> {
+    return this._client.get('/v1/candles/weeks', { query, ...options, __security: {} });
+  }
+
+  /**
+   * List Year Candles
+   *
+   * GET /v1/candles/years
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-candles-years
+   * - docs(global): https://global-docs.upbit.com/reference/list-candles-years
+   *
+   * @example
+   * ```ts
+   * const candlePeriods = await client.candles.listYears({
+   *   market: 'KRW-BTC',
+   * });
+   * ```
+   */
+  listYears(query: CandleListYearsParams, options?: RequestOptions): APIPromise<CandleListYearsResponse> {
+    return this._client.get('/v1/candles/years', { query, ...options, __security: {} });
+  }
+}
+
+export interface Candle {
+  /**
+   * The total trade amount (in the quoted currency) accumulated during the candle
+   * period.
+   */
+  candle_acc_trade_price: string;
+
+  /**
+   * The total traded volume (in the base asset) accumulated during the candle
+   * period.
+   */
+  candle_acc_trade_volume: string;
+
+  /**
+   * Start time of the candle period in KST. Supported in KOREA only.
+   *
+   * [Format]: yyyy-MM-dd'T'HH:mm:ss
+   */
+  candle_date_time_kst: string;
+
+  /**
+   * Start time of the candle period in UTC.
+   *
+   * [Format]: yyyy-MM-dd'T'HH:mm:ss
+   */
+  candle_date_time_utc: string;
+
+  /**
+   * The highest trading price, recorded during the candle period.
+   */
+  high_price: string;
+
+  /**
+   * The lowest trading price. recorded during the candle period.
+   */
+  low_price: string;
+
+  /**
+   * Trading pair code representing the market.
+   *
+   * [Example]: "SGD-BTC"
+   */
+  market: string;
+
+  /**
+   * The opening price of the candle, representing the first trading price during the
+   * candle period.
+   */
+  opening_price: string;
+
+  /**
+   * The timestamp (in milliseconds) when the last tick of the candle was recorded.
+   */
+  timestamp: number;
+
+  /**
+   * The closing price of the candle, representing the last trading price during the
+   * candle period.
+   */
+  trade_price: string;
+}
+
+export interface CandlePeriod extends Candle {
+  /**
+   * Start date of candle aggregation period (yyyy-MM-dd).
+   */
+  first_day_of_period: string;
+}
+
+export type CandleListDaysResponse = Array<CandleListDaysResponse.CandleListDaysResponseItem>;
+
+export namespace CandleListDaysResponse {
+  export interface CandleListDaysResponseItem extends CandlesAPI.Candle {
+    /**
+     * Price change = trade_price - prev_closing_price.
+     */
+    change_price: string;
+
+    /**
+     * Change rate = (trade_price - prev_closing_price) / prev_closing_price.
+     */
+    change_rate: string;
+
+    /**
+     * Previous day's closing price (UTC-based).
+     */
+    prev_closing_price: string;
+
+    /**
+     * Closing price converted per converting_price_unit. Null for non-digital asset
+     * markets.
+     */
+    converted_trade_price?: string;
+  }
+}
+
+export type CandleListMinutesResponse = Array<Candle>;
+
+export type CandleListMonthsResponse = Array<CandlePeriod>;
+
+export type CandleListSecondsResponse = Array<Candle>;
+
+export type CandleListWeeksResponse = Array<CandlePeriod>;
+
+export type CandleListYearsResponse = Array<CandlePeriod>;
+
+export interface CandleListDaysParams {
+  /**
+   * Trading pair code to query.
+   */
+  market: string;
+
+  /**
+   * Currency to convert the closing price into. When specified, the response
+   * includes a "converted_trade_price" field with the closing price converted to the
+   * given currency.
+   *
+   * [Example] Specifying "KRW" returns the closing price converted to KRW.
+   */
+  converting_price_unit?: string;
+
+  /**
+   * Number of candles to retrieve.
+   *
+   * Up to 200 candles are supported. Default: 1.
+   */
+  count?: number;
+
+  /**
+   * End time of the query range. Retrieves candles before the specified time. If not
+   * specified, the most recent candles are returned.
+   *
+   * Accepts ISO 8601 datetime format.
+   */
+  to?: string;
+}
+
+export interface CandleListMinutesParams {
+  /**
+   * Trading pair code to query.
+   */
+  market: string;
+
+  /**
+   * Number of candles to retrieve.
+   *
+   * Up to 200 candles are supported. Default: 1.
+   */
+  count?: number;
+
+  /**
+   * End time of the query range. Retrieves candles before the specified time. If not
+   * specified, the most recent candles are returned.
+   *
+   * Accepts ISO 8601 datetime format.
+   *
+   * [Example] 2025-06-24T04:56:53Z 2025-06-24 04:56:53 2025-06-24T13:56:53+08:00
+   */
+  to?: string;
+}
+
+export interface CandleListMonthsParams {
+  /**
+   * Trading pair code to query.
+   */
+  market: string;
+
+  /**
+   * Number of candles to retrieve. Up to 200, default: 1.
+   */
+  count?: number;
+
+  /**
+   * End time of the query range. If not specified, the most recent candles are
+   * returned.
+   *
+   * Accepts ISO 8601 datetime format.
+   */
+  to?: string;
+}
+
+export interface CandleListSecondsParams {
+  /**
+   * Trading pair code to query.
+   */
+  market: string;
+
+  /**
+   * Number of candles to retrieve.
+   *
+   * Up to 200 candles are supported. Default: 1.
+   */
+  count?: number;
+
+  /**
+   * End time of the query range. Retrieves candles before the specified time. If not
+   * specified, the most recent candles are returned.
+   *
+   * Accepts ISO 8601 datetime format. URL encoding is required for spaces and
+   * special characters.
+   *
+   * [Example] 2025-06-24T04:56:53Z 2025-06-24 04:56:53 2025-06-24T13:56:53+08:00
+   *
+   * Second candles only support data up to 3 months prior. An empty array is
+   * returned for older times.
+   */
+  to?: string;
+}
+
+export interface CandleListWeeksParams {
+  /**
+   * Trading pair code to query.
+   */
+  market: string;
+
+  /**
+   * Number of candles to retrieve. Up to 200, default: 1.
+   */
+  count?: number;
+
+  /**
+   * End time of the query range. Retrieves candles before the specified time. If not
+   * specified, the most recent candles are returned.
+   */
+  to?: string;
+}
+
+export interface CandleListYearsParams {
+  /**
+   * Trading pair code to query.
+   */
+  market: string;
+
+  /**
+   * Number of candles to retrieve. Up to 200, default: 1.
+   */
+  count?: number;
+
+  /**
+   * End time of the query range. ISO 8601 format.
+   */
+  to?: string;
+}
+
+export declare namespace Candles {
+  export {
+    type Candle as Candle,
+    type CandlePeriod as CandlePeriod,
+    type CandleListDaysResponse as CandleListDaysResponse,
+    type CandleListMinutesResponse as CandleListMinutesResponse,
+    type CandleListMonthsResponse as CandleListMonthsResponse,
+    type CandleListSecondsResponse as CandleListSecondsResponse,
+    type CandleListWeeksResponse as CandleListWeeksResponse,
+    type CandleListYearsResponse as CandleListYearsResponse,
+    type CandleListDaysParams as CandleListDaysParams,
+    type CandleListMinutesParams as CandleListMinutesParams,
+    type CandleListMonthsParams as CandleListMonthsParams,
+    type CandleListSecondsParams as CandleListSecondsParams,
+    type CandleListWeeksParams as CandleListWeeksParams,
+    type CandleListYearsParams as CandleListYearsParams,
+  };
+}