@upbit-official/upbit-sdk 0.9.0

package/src/client.ts

@@ -0,0 +1,1112 @@
+
+import type { RequestInit, RequestInfo, BodyInit } from './internal/builtin-types';
+import type { HTTPMethod, PromiseOrValue, MergedRequestInit, FinalizedRequestInit } from './internal/types';
+import { uuid4 } from './internal/utils/uuid';
+import { validatePositiveInteger, isAbsoluteURL, safeJSON } from './internal/utils/values';
+import { sleep } from './internal/utils/sleep';
+export type { Logger, LogLevel } from './internal/utils/log';
+import { castToError, isAbortError } from './internal/errors';
+import type { APIResponseProps } from './internal/parse';
+import * as Shims from './internal/shims';
+import * as Opts from './internal/request-options';
+import { stringifyQuery } from './internal/utils/query';
+import { VERSION } from './version';
+import * as Errors from './core/error';
+import * as Pagination from './core/pagination';
+import {
+  AbstractPage,
+  type PageNumberPageParams,
+  PageNumberPageResponse,
+  type UuidCursorIDPageParams,
+  UuidCursorIDPageResponse,
+} from './core/pagination';
+import * as Uploads from './core/uploads';
+import * as API from './resources/index';
+import { APIPromise } from './core/api-promise';
+import { AccountListResponse, Accounts } from './resources/accounts';
+import { APIKeyListResponse, APIKeys } from './resources/api-keys';
+import {
+  Candle,
+  CandleListDaysParams,
+  CandleListDaysResponse,
+  CandleListMinutesParams,
+  CandleListMinutesResponse,
+  CandleListMonthsParams,
+  CandleListMonthsResponse,
+  CandleListSecondsParams,
+  CandleListSecondsResponse,
+  CandleListWeeksParams,
+  CandleListWeeksResponse,
+  CandleListYearsParams,
+  CandleListYearsResponse,
+  CandlePeriod,
+  Candles,
+} from './resources/candles';
+import {
+  Deposit,
+  DepositAddress,
+  DepositCreateCoinAddressParams,
+  DepositCreateCoinAddressResponse,
+  DepositDepositKrwParams,
+  DepositListCoinAddressesResponse,
+  DepositListParams,
+  DepositRetrieveChanceParams,
+  DepositRetrieveChanceResponse,
+  DepositRetrieveCoinAddressParams,
+  DepositRetrieveParams,
+  Deposits,
+  DepositsUuidCursorIDPage,
+} from './resources/deposits';
+import {
+  OrderbookListInstrumentsParams,
+  OrderbookListInstrumentsResponse,
+  OrderbookListParams,
+  OrderbookListResponse,
+  Orderbooks,
+} from './resources/orderbooks';
+import {
+  BatchCancelResult,
+  ClosedOrderState,
+  OpenOrderState,
+  OrdTypeEnum,
+  Order,
+  OrderCancelAndNewParams,
+  OrderCancelByUuidsParams,
+  OrderCancelOpenParams,
+  OrderCancelParams,
+  OrderCreateParams,
+  OrderListByUuidsParams,
+  OrderListByUuidsResponse,
+  OrderListClosedParams,
+  OrderListClosedResponse,
+  OrderListOpenParams,
+  OrderRetrieveChanceParams,
+  OrderRetrieveChanceResponse,
+  OrderRetrieveParams,
+  OrderTestCreateParams,
+  Orders,
+  OrdersPageNumberPage,
+  SideEnum,
+  SmpTypeEnum,
+  TimeInForceEnum,
+} from './resources/orders';
+import {
+  Ticker,
+  TickerListByQuoteCurrenciesParams,
+  TickerListByQuoteCurrenciesResponse,
+  TickerListByTradingPairsParams,
+  TickerListByTradingPairsResponse,
+  Tickers,
+} from './resources/tickers';
+import { TradeListParams, TradeListResponse, Trades } from './resources/trades';
+import { TradingPairListParams, TradingPairListResponse, TradingPairs } from './resources/trading-pairs';
+import {
+  TravelRule,
+  TravelRuleListVaspsResponse,
+  TravelRuleVerifyDepositByTxidParams,
+  TravelRuleVerifyDepositByUuidParams,
+  VerificationResult,
+} from './resources/travel-rule';
+import { WalletStatus, WalletStatusListResponse } from './resources/wallet-status';
+import {
+  Withdraw,
+  WithdrawCancelWithdrawalParams,
+  WithdrawCreateKrwWithdrawalParams,
+  WithdrawCreateKrwWithdrawalResponse,
+  WithdrawCreateWithdrawalParams,
+  WithdrawListCoinAddressesResponse,
+  WithdrawListParams,
+  WithdrawRetrieveChanceParams,
+  WithdrawRetrieveChanceResponse,
+  WithdrawRetrieveParams,
+  Withdraws,
+  WithdrawsUuidCursorIDPage,
+} from './resources/withdraws';
+import {
+  ConnectPrivateClientEvent,
+  ConnectPrivateServerEvent,
+  WsPrivate,
+} from './resources/ws-private/ws-private';
+import {
+  ConnectPublicClientEvent,
+  ConnectPublicServerEvent,
+  WsPublic,
+} from './resources/ws-public/ws-public';
+import { type Fetch } from './internal/builtin-types';
+import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
+import { FinalRequestOptions, RequestOptions } from './internal/request-options';
+import { readEnv } from './internal/utils/env';
+import { createJwtToken } from './lib/jwtAuth';
+import { WsStream } from './lib/ws';
+import {
+  type LogLevel,
+  type Logger,
+  formatRequestDetails,
+  loggerFor,
+  parseLogLevel,
+} from './internal/utils/log';
+import { isEmptyObj } from './internal/utils/values';
+
+const environments = {
+  kr: 'https://api.upbit.com',
+  sg: 'https://sg-api.upbit.com',
+  id: 'https://id-api.upbit.com',
+  th: 'https://th-api.upbit.com',
+};
+type Environment = keyof typeof environments;
+
+export interface ClientOptions {
+  /**
+   * The access key provided by Upbit for API authentication.
+   * For more details, please refer to https://docs.upbit.com/reference/auth.
+   *
+   */
+  accessKey?: string | null | undefined;
+
+  /**
+   * The secret key used to sign API requests for secure verification.
+   * For more details, please refer to https://docs.upbit.com/reference/auth.
+   *
+   */
+  secretKey?: string | null | undefined;
+
+  /**
+   * Specifies the environment to use for the API.
+   *
+   * Each environment maps to a different base URL:
+   * - `kr` corresponds to `https://api.upbit.com`
+   * - `sg` corresponds to `https://sg-api.upbit.com`
+   * - `id` corresponds to `https://id-api.upbit.com`
+   * - `th` corresponds to `https://th-api.upbit.com`
+   */
+  environment?: Environment | undefined;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   *
+   * Defaults to process.env['UPBIT_BASE_URL'].
+   */
+  baseURL?: string | null | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   *
+   * @unit milliseconds
+   */
+  timeout?: number | undefined;
+  /**
+   * Additional `RequestInit` options to be passed to `fetch` calls.
+   * Properties will be overridden by per-request `fetchOptions`.
+   */
+  fetchOptions?: MergedRequestInit | undefined;
+
+  /**
+   * Specify a custom `fetch` function implementation.
+   *
+   * If not provided, we expect that `fetch` is defined globally.
+   */
+  fetch?: Fetch | undefined;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
+  maxRetries?: number | undefined;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `null` in request options.
+   */
+  defaultHeaders?: HeadersLike | undefined;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
+  defaultQuery?: Record<string, string | undefined> | undefined;
+
+  /**
+   * Set the log level.
+   *
+   * Defaults to process.env['UPBIT_LOG'] or 'warn' if it isn't set.
+   */
+  logLevel?: LogLevel | undefined;
+
+  /**
+   * Set the logger.
+   *
+   * Defaults to globalThis.console.
+   */
+  logger?: Logger | undefined;
+}
+
+/**
+ * API Client for interfacing with the Upbit API.
+ */
+export class Upbit {
+  accessKey: string | null;
+  secretKey: string | null;
+
+  baseURL: string;
+  maxRetries: number;
+  timeout: number;
+  logger: Logger;
+  logLevel: LogLevel | undefined;
+  fetchOptions: MergedRequestInit | undefined;
+
+  private fetch: Fetch;
+  #encoder: Opts.RequestEncoder;
+  protected idempotencyHeader?: string;
+  private _options: ClientOptions;
+
+  /**
+   * API Client for interfacing with the Upbit API.
+   *
+   * @param {string | null | undefined} [opts.accessKey=process.env['UPBIT_ACCESS_KEY'] ?? null]
+   * @param {string | null | undefined} [opts.secretKey=process.env['UPBIT_SECRET_KEY'] ?? null]
+   * @param {Environment} [opts.environment=kr] - Specifies the environment URL to use for the API.
+   * @param {string} [opts.baseURL=process.env['UPBIT_BASE_URL'] ?? https://api.upbit.com] - Override the default base URL for the API.
+   * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
+   * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
+   * @param {Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+   * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
+   * @param {HeadersLike} opts.defaultHeaders - Default headers to include with every request to the API.
+   * @param {Record<string, string | undefined>} opts.defaultQuery - Default query parameters to include with every request to the API.
+   */
+  constructor({
+    baseURL = readEnv('UPBIT_BASE_URL'),
+    accessKey = readEnv('UPBIT_ACCESS_KEY') ?? null,
+    secretKey = readEnv('UPBIT_SECRET_KEY') ?? null,
+    ...opts
+  }: ClientOptions = {}) {
+    const options: ClientOptions = {
+      accessKey,
+      secretKey,
+      ...opts,
+      baseURL,
+      environment: opts.environment ?? 'kr',
+    };
+
+    if (baseURL && opts.environment) {
+      throw new Errors.UpbitError(
+        'Ambiguous URL; The `baseURL` option (or UPBIT_BASE_URL env var) and the `environment` option are given. If you want to use the environment you must pass baseURL: null',
+      );
+    }
+
+    this.baseURL = options.baseURL || environments[options.environment || 'kr'];
+    this.timeout = options.timeout ?? Upbit.DEFAULT_TIMEOUT /* 1 minute */;
+    this.logger = options.logger ?? console;
+    const defaultLogLevel = 'warn';
+    // Set default logLevel early so that we can log a warning in parseLogLevel.
+    this.logLevel = defaultLogLevel;
+    this.logLevel =
+      parseLogLevel(options.logLevel, 'ClientOptions.logLevel', this) ??
+      parseLogLevel(readEnv('UPBIT_LOG'), "process.env['UPBIT_LOG']", this) ??
+      defaultLogLevel;
+    this.fetchOptions = options.fetchOptions;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.fetch = options.fetch ?? Shims.getDefaultFetch();
+    this.#encoder = Opts.FallbackEncoder;
+
+    this._options = options;
+
+    this.accessKey = accessKey;
+    this.secretKey = secretKey;
+  }
+
+  /**
+   * Create a new client instance re-using the same options given to the current client with optional overriding.
+   */
+  withOptions(options: Partial<ClientOptions>): this {
+    const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)({
+      ...this._options,
+      environment: options.environment ? options.environment : undefined,
+      baseURL: options.environment ? undefined : this.baseURL,
+      maxRetries: this.maxRetries,
+      timeout: this.timeout,
+      logger: this.logger,
+      logLevel: this.logLevel,
+      fetch: this.fetch,
+      fetchOptions: this.fetchOptions,
+      accessKey: this.accessKey,
+      secretKey: this.secretKey,
+      ...options,
+    });
+    return client;
+  }
+
+  /**
+   * Check whether the base URL is set to its default.
+   */
+  #baseURLOverridden(): boolean {
+    return this.baseURL !== environments[this._options.environment || 'kr'];
+  }
+
+  protected defaultQuery(): Record<string, string | undefined> | undefined {
+    return this._options.defaultQuery;
+  }
+
+  protected validateHeaders({ values, nulls }: NullableHeaders) {
+    return;
+  }
+
+  protected async authHeaders(
+    opts: FinalRequestOptions,
+    schemes: { bearerAuth?: boolean },
+  ): Promise<NullableHeaders | undefined> {
+    return buildHeaders([schemes.bearerAuth ? await this.bearerAuth(opts) : null]);
+  }
+
+  protected async bearerAuth(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
+    if (this.accessKey == null || this.secretKey == null) {
+      return undefined;
+    }
+    const queryParams =
+      (opts.query as Record<string, unknown> | null | undefined) ??
+      (opts.body != null && typeof opts.body === 'object' && !Array.isArray(opts.body) ?
+        (opts.body as Record<string, unknown>)
+      : null);
+    const token = createJwtToken(this.accessKey, this.secretKey, queryParams);
+    return buildHeaders([{ Authorization: `Bearer ${token}` }]);
+  }
+
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
+  }
+
+  private getUserAgent(): string {
+    return `${this.constructor.name}/JS ${VERSION}`;
+  }
+
+  protected defaultIdempotencyKey(): string {
+    return `node-retry-${uuid4()}`;
+  }
+
+  protected makeStatusError(
+    status: number,
+    error: Object,
+    message: string | undefined,
+    headers: Headers,
+  ): Errors.APIError {
+    return Errors.APIError.generate(status, error, message, headers);
+  }
+
+  buildURL(
+    path: string,
+    query: Record<string, unknown> | null | undefined,
+    defaultBaseURL?: string | undefined,
+  ): string {
+    const baseURL = (!this.#baseURLOverridden() && defaultBaseURL) || this.baseURL;
+    const url =
+      isAbsoluteURL(path) ?
+        new URL(path)
+      : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
+
+    const defaultQuery = this.defaultQuery();
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
+    }
+
+    if (typeof query === 'object' && query && !Array.isArray(query)) {
+      url.search = this.stringifyQuery(query);
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Used as a callback for mutating the given `FinalRequestOptions` object.
+   */
+  protected async prepareOptions(options: FinalRequestOptions): Promise<void> {}
+
+  /**
+   * Used as a callback for mutating the given `RequestInit` object.
+   *
+   * This is useful for cases where you want to add certain headers based off of
+   * the request properties, e.g. `method` or `url`.
+   */
+  protected async prepareRequest(
+    request: RequestInit,
+    { url, options }: { url: string; options: FinalRequestOptions },
+  ): Promise<void> {}
+
+  get<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp> {
+    return this.methodRequest('get', path, opts);
+  }
+
+  post<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp> {
+    return this.methodRequest('post', path, opts);
+  }
+
+  patch<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp> {
+    return this.methodRequest('patch', path, opts);
+  }
+
+  put<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp> {
+    return this.methodRequest('put', path, opts);
+  }
+
+  delete<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp> {
+    return this.methodRequest('delete', path, opts);
+  }
+
+  private methodRequest<Rsp>(
+    method: HTTPMethod,
+    path: string,
+    opts?: PromiseOrValue<RequestOptions>,
+  ): APIPromise<Rsp> {
+    return this.request(
+      Promise.resolve(opts).then((opts) => {
+        return { method, path, ...opts };
+      }),
+    );
+  }
+
+  request<Rsp>(
+    options: PromiseOrValue<FinalRequestOptions>,
+    remainingRetries: number | null = null,
+  ): APIPromise<Rsp> {
+    return new APIPromise(this, this.makeRequest(options, remainingRetries, undefined));
+  }
+
+  private async makeRequest(
+    optionsInput: PromiseOrValue<FinalRequestOptions>,
+    retriesRemaining: number | null,
+    retryOfRequestLogID: string | undefined,
+  ): Promise<APIResponseProps> {
+    const options = await optionsInput;
+    const maxRetries = options.maxRetries ?? this.maxRetries;
+    if (retriesRemaining == null) {
+      retriesRemaining = maxRetries;
+    }
+
+    await this.prepareOptions(options);
+
+    const { req, url, timeout } = await this.buildRequest(options, {
+      retryCount: maxRetries - retriesRemaining,
+    });
+
+    await this.prepareRequest(req, { url, options });
+
+    /** Not an API request ID, just for correlating local log entries. */
+    const requestLogID = 'log_' + ((Math.random() * (1 << 24)) | 0).toString(16).padStart(6, '0');
+    const retryLogStr = retryOfRequestLogID === undefined ? '' : `, retryOf: ${retryOfRequestLogID}`;
+    const startTime = Date.now();
+
+    loggerFor(this).debug(
+      `[${requestLogID}] sending request`,
+      formatRequestDetails({
+        retryOfRequestLogID,
+        method: options.method,
+        url,
+        options,
+        headers: req.headers,
+      }),
+    );
+
+    if (options.signal?.aborted) {
+      throw new Errors.APIUserAbortError();
+    }
+
+    const controller = new AbortController();
+    const response = await this.fetchWithTimeout(url, req, timeout, controller).catch(castToError);
+    const headersTime = Date.now();
+
+    if (response instanceof globalThis.Error) {
+      const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
+      if (options.signal?.aborted) {
+        throw new Errors.APIUserAbortError();
+      }
+      // detect native connection timeout errors
+      // deno throws "TypeError: error sending request for url (https://example/): client error (Connect): tcp connect error: Operation timed out (os error 60): Operation timed out (os error 60)"
+      // undici throws "TypeError: fetch failed" with cause "ConnectTimeoutError: Connect Timeout Error (attempted address: example:443, timeout: 1ms)"
+      // others do not provide enough information to distinguish timeouts from other connection errors
+      const isTimeout =
+        isAbortError(response) ||
+        /timed? ?out/i.test(String(response) + ('cause' in response ? String(response.cause) : ''));
+      if (retriesRemaining) {
+        loggerFor(this).info(
+          `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} - ${retryMessage}`,
+        );
+        loggerFor(this).debug(
+          `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} (${retryMessage})`,
+          formatRequestDetails({
+            retryOfRequestLogID,
+            url,
+            durationMs: headersTime - startTime,
+            message: response.message,
+          }),
+        );
+        return this.retryRequest(options, retriesRemaining, retryOfRequestLogID ?? requestLogID);
+      }
+      loggerFor(this).info(
+        `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} - error; no more retries left`,
+      );
+      loggerFor(this).debug(
+        `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} (error; no more retries left)`,
+        formatRequestDetails({
+          retryOfRequestLogID,
+          url,
+          durationMs: headersTime - startTime,
+          message: response.message,
+        }),
+      );
+      if (isTimeout) {
+        throw new Errors.APIConnectionTimeoutError();
+      }
+      throw new Errors.APIConnectionError({ cause: response });
+    }
+
+    const responseInfo = `[${requestLogID}${retryLogStr}] ${req.method} ${url} ${
+      response.ok ? 'succeeded' : 'failed'
+    } with status ${response.status} in ${headersTime - startTime}ms`;
+
+    if (!response.ok) {
+      const shouldRetry = await this.shouldRetry(response);
+      if (retriesRemaining && shouldRetry) {
+        const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
+
+        // We don't need the body of this response.
+        await Shims.CancelReadableStream(response.body);
+        loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
+        loggerFor(this).debug(
+          `[${requestLogID}] response error (${retryMessage})`,
+          formatRequestDetails({
+            retryOfRequestLogID,
+            url: response.url,
+            status: response.status,
+            headers: response.headers,
+            durationMs: headersTime - startTime,
+          }),
+        );
+        return this.retryRequest(
+          options,
+          retriesRemaining,
+          retryOfRequestLogID ?? requestLogID,
+          response.headers,
+        );
+      }
+
+      const retryMessage = shouldRetry ? `error; no more retries left` : `error; not retryable`;
+
+      loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
+
+      const errText = await response.text().catch((err: any) => castToError(err).message);
+      const errJSON = safeJSON(errText) as any;
+      const errMessage = errJSON ? undefined : errText;
+
+      loggerFor(this).debug(
+        `[${requestLogID}] response error (${retryMessage})`,
+        formatRequestDetails({
+          retryOfRequestLogID,
+          url: response.url,
+          status: response.status,
+          headers: response.headers,
+          message: errMessage,
+          durationMs: Date.now() - startTime,
+        }),
+      );
+
+      const err = this.makeStatusError(response.status, errJSON, errMessage, response.headers);
+      throw err;
+    }
+
+    loggerFor(this).info(responseInfo);
+    loggerFor(this).debug(
+      `[${requestLogID}] response start`,
+      formatRequestDetails({
+        retryOfRequestLogID,
+        url: response.url,
+        status: response.status,
+        headers: response.headers,
+        durationMs: headersTime - startTime,
+      }),
+    );
+
+    return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
+  }
+
+  getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
+    path: string,
+    Page: new (...args: any[]) => PageClass,
+    opts?: PromiseOrValue<RequestOptions>,
+  ): Pagination.PagePromise<PageClass, Item> {
+    return this.requestAPIList(
+      Page,
+      opts && 'then' in opts ?
+        opts.then((opts) => ({ method: 'get', path, ...opts }))
+      : { method: 'get', path, ...opts },
+    );
+  }
+
+  requestAPIList<
+    Item = unknown,
+    PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>,
+  >(
+    Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
+    options: PromiseOrValue<FinalRequestOptions>,
+  ): Pagination.PagePromise<PageClass, Item> {
+    const request = this.makeRequest(options, null, undefined);
+    return new Pagination.PagePromise<PageClass, Item>(this as any as Upbit, request, Page);
+  }
+
+  async fetchWithTimeout(
+    url: RequestInfo,
+    init: RequestInit | undefined,
+    ms: number,
+    controller: AbortController,
+  ): Promise<Response> {
+    const { signal, method, ...options } = init || {};
+    const abort = this._makeAbort(controller);
+    if (signal) signal.addEventListener('abort', abort, { once: true });
+
+    const timeout = setTimeout(abort, ms);
+
+    const isReadableBody =
+      ((globalThis as any).ReadableStream && options.body instanceof (globalThis as any).ReadableStream) ||
+      (typeof options.body === 'object' && options.body !== null && Symbol.asyncIterator in options.body);
+
+    const fetchOptions: RequestInit = {
+      signal: controller.signal as any,
+      ...(isReadableBody ? { duplex: 'half' } : {}),
+      method: 'GET',
+      ...options,
+    };
+    if (method) {
+      // Custom methods like 'patch' need to be uppercased
+      // See https://github.com/nodejs/undici/issues/2294
+      fetchOptions.method = method.toUpperCase();
+    }
+
+    try {
+      // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
+      return await this.fetch.call(undefined, url, fetchOptions);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private async shouldRetry(response: Response): Promise<boolean> {
+    // Note this is not a standard header.
+    const shouldRetryHeader = response.headers.get('x-should-retry');
+
+    // If the server explicitly says whether or not to retry, obey.
+    if (shouldRetryHeader === 'true') return true;
+    if (shouldRetryHeader === 'false') return false;
+
+    // Retry on request timeouts.
+    if (response.status === 408) return true;
+
+    // Retry on lock timeouts.
+    if (response.status === 409) return true;
+
+    // Retry on rate limits.
+    if (response.status === 429) return true;
+
+    // Retry internal errors.
+    if (response.status >= 500) return true;
+
+    return false;
+  }
+
+  private async retryRequest(
+    options: FinalRequestOptions,
+    retriesRemaining: number,
+    requestLogID: string,
+    responseHeaders?: Headers | undefined,
+  ): Promise<APIResponseProps> {
+    let timeoutMillis: number | undefined;
+
+    // Note the `retry-after-ms` header may not be standard, but is a good idea and we'd like proactive support for it.
+    const retryAfterMillisHeader = responseHeaders?.get('retry-after-ms');
+    if (retryAfterMillisHeader) {
+      const timeoutMs = parseFloat(retryAfterMillisHeader);
+      if (!Number.isNaN(timeoutMs)) {
+        timeoutMillis = timeoutMs;
+      }
+    }
+
+    // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
+    const retryAfterHeader = responseHeaders?.get('retry-after');
+    if (retryAfterHeader && !timeoutMillis) {
+      const timeoutSeconds = parseFloat(retryAfterHeader);
+      if (!Number.isNaN(timeoutSeconds)) {
+        timeoutMillis = timeoutSeconds * 1000;
+      } else {
+        timeoutMillis = Date.parse(retryAfterHeader) - Date.now();
+      }
+    }
+
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
+      const maxRetries = options.maxRetries ?? this.maxRetries;
+      timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
+    }
+    await sleep(timeoutMillis);
+
+    return this.makeRequest(options, retriesRemaining - 1, requestLogID);
+  }
+
+  private calculateDefaultRetryTimeoutMillis(retriesRemaining: number, maxRetries: number): number {
+    const initialRetryDelay = 0.5;
+    const maxRetryDelay = 8.0;
+
+    const numRetries = maxRetries - retriesRemaining;
+
+    // Apply exponential backoff, but not more than the max.
+    const sleepSeconds = Math.min(initialRetryDelay * Math.pow(2, numRetries), maxRetryDelay);
+
+    // Apply some jitter, take up to at most 25 percent of the retry time.
+    const jitter = 1 - Math.random() * 0.25;
+
+    return sleepSeconds * jitter * 1000;
+  }
+
+  async buildRequest(
+    inputOptions: FinalRequestOptions,
+    { retryCount = 0 }: { retryCount?: number } = {},
+  ): Promise<{ req: FinalizedRequestInit; url: string; timeout: number }> {
+    const options = { ...inputOptions };
+    const { method, path, query, defaultBaseURL } = options;
+
+    const url = this.buildURL(path!, query as Record<string, unknown>, defaultBaseURL);
+    if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
+    options.timeout = options.timeout ?? this.timeout;
+    const { bodyHeaders, body } = this.buildBody({ options });
+    const reqHeaders = await this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
+
+    const req: FinalizedRequestInit = {
+      method,
+      headers: reqHeaders,
+      ...(options.signal && { signal: options.signal }),
+      ...((globalThis as any).ReadableStream &&
+        body instanceof (globalThis as any).ReadableStream && { duplex: 'half' }),
+      ...(body && { body }),
+      ...((this.fetchOptions as any) ?? {}),
+      ...((options.fetchOptions as any) ?? {}),
+    };
+
+    return { req, url, timeout: options.timeout };
+  }
+
+  private async buildHeaders({
+    options,
+    method,
+    bodyHeaders,
+    retryCount,
+  }: {
+    options: FinalRequestOptions;
+    method: HTTPMethod;
+    bodyHeaders: HeadersLike;
+    retryCount: number;
+  }): Promise<Headers> {
+    let idempotencyHeaders: HeadersLike = {};
+    if (this.idempotencyHeader && method !== 'get') {
+      if (!options.idempotencyKey) options.idempotencyKey = this.defaultIdempotencyKey();
+      idempotencyHeaders[this.idempotencyHeader] = options.idempotencyKey;
+    }
+
+    const headers = buildHeaders([
+      idempotencyHeaders,
+      {
+        Accept: 'application/json',
+        'User-Agent': this.getUserAgent(),
+        'X-Upbit-SDK-Lang': 'typescript',
+        'X-Upbit-SDK-Version': VERSION,
+        'X-Upbit-Runtime': getRuntimeName(),
+        'X-Upbit-Runtime-Version': getRuntimeVersion(),
+      },
+      await this.authHeaders(options, options.__security ?? { bearerAuth: true }),
+      this._options.defaultHeaders,
+      bodyHeaders,
+      options.headers,
+    ]);
+
+    this.validateHeaders(headers);
+
+    return headers.values;
+  }
+
+  private _makeAbort(controller: AbortController) {
+    // note: we can't just inline this method inside `fetchWithTimeout()` because then the closure
+    //       would capture all request options, and cause a memory leak.
+    return () => controller.abort();
+  }
+
+  private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
+    bodyHeaders: HeadersLike;
+    body: BodyInit | undefined;
+  } {
+    if (!body) {
+      return { bodyHeaders: undefined, body: undefined };
+    }
+    const headers = buildHeaders([rawHeaders]);
+    if (
+      // Pass raw type verbatim
+      ArrayBuffer.isView(body) ||
+      body instanceof ArrayBuffer ||
+      body instanceof DataView ||
+      (typeof body === 'string' &&
+        // Preserve legacy string encoding behavior for now
+        headers.values.has('content-type')) ||
+      // `Blob` is superset of `File`
+      ((globalThis as any).Blob && body instanceof (globalThis as any).Blob) ||
+      // `FormData` -> `multipart/form-data`
+      body instanceof FormData ||
+      // `URLSearchParams` -> `application/x-www-form-urlencoded`
+      body instanceof URLSearchParams ||
+      // Send chunked stream (each chunk has own `length`)
+      ((globalThis as any).ReadableStream && body instanceof (globalThis as any).ReadableStream)
+    ) {
+      return { bodyHeaders: undefined, body: body as BodyInit };
+    } else if (
+      typeof body === 'object' &&
+      (Symbol.asyncIterator in body ||
+        (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
+    ) {
+      return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
+    } else {
+      return this.#encoder({ body, headers });
+    }
+  }
+
+  private _wsStream: WsStream | undefined;
+
+  /** Convenience accessor for WebSocket streams. */
+  get wsStream(): WsStream {
+    return (this._wsStream ??= new WsStream(this));
+  }
+
+  static Upbit = this;
+  static DEFAULT_TIMEOUT = 60000; // 1 minute
+
+  static UpbitError = Errors.UpbitError;
+  static APIError = Errors.APIError;
+  static APIConnectionError = Errors.APIConnectionError;
+  static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static APIUserAbortError = Errors.APIUserAbortError;
+  static NotFoundError = Errors.NotFoundError;
+  static ConflictError = Errors.ConflictError;
+  static RateLimitError = Errors.RateLimitError;
+  static RateLimitPenaltyError = Errors.RateLimitPenaltyError;
+  static BadRequestError = Errors.BadRequestError;
+  static AuthenticationError = Errors.AuthenticationError;
+  static InternalServerError = Errors.InternalServerError;
+  static PermissionDeniedError = Errors.PermissionDeniedError;
+  static UnprocessableEntityError = Errors.UnprocessableEntityError;
+
+  static toFile = Uploads.toFile;
+
+  accounts: API.Accounts = new API.Accounts(this);
+  travelRule: API.TravelRule = new API.TravelRule(this);
+  walletStatus: API.WalletStatus = new API.WalletStatus(this);
+  apiKeys: API.APIKeys = new API.APIKeys(this);
+  orders: API.Orders = new API.Orders(this);
+  withdraws: API.Withdraws = new API.Withdraws(this);
+  deposits: API.Deposits = new API.Deposits(this);
+  tradingPairs: API.TradingPairs = new API.TradingPairs(this);
+  tickers: API.Tickers = new API.Tickers(this);
+  orderbooks: API.Orderbooks = new API.Orderbooks(this);
+  trades: API.Trades = new API.Trades(this);
+  candles: API.Candles = new API.Candles(this);
+  wsPublic: API.WsPublic = new API.WsPublic(this);
+  wsPrivate: API.WsPrivate = new API.WsPrivate(this);
+}
+
+Upbit.Accounts = Accounts;
+Upbit.TravelRule = TravelRule;
+Upbit.WalletStatus = WalletStatus;
+Upbit.APIKeys = APIKeys;
+Upbit.Orders = Orders;
+Upbit.Withdraws = Withdraws;
+Upbit.Deposits = Deposits;
+Upbit.TradingPairs = TradingPairs;
+Upbit.Tickers = Tickers;
+Upbit.Orderbooks = Orderbooks;
+Upbit.Trades = Trades;
+Upbit.Candles = Candles;
+Upbit.WsPublic = WsPublic;
+Upbit.WsPrivate = WsPrivate;
+
+export declare namespace Upbit {
+  export type RequestOptions = Opts.RequestOptions;
+
+  export import PageNumberPage = Pagination.PageNumberPage;
+  export {
+    type PageNumberPageParams as PageNumberPageParams,
+    type PageNumberPageResponse as PageNumberPageResponse,
+  };
+
+  export import UuidCursorIDPage = Pagination.UuidCursorIDPage;
+  export {
+    type UuidCursorIDPageParams as UuidCursorIDPageParams,
+    type UuidCursorIDPageResponse as UuidCursorIDPageResponse,
+  };
+
+  export { Accounts as Accounts, type AccountListResponse as AccountListResponse };
+
+  export {
+    TravelRule as TravelRule,
+    type VerificationResult as VerificationResult,
+    type TravelRuleListVaspsResponse as TravelRuleListVaspsResponse,
+    type TravelRuleVerifyDepositByTxidParams as TravelRuleVerifyDepositByTxidParams,
+    type TravelRuleVerifyDepositByUuidParams as TravelRuleVerifyDepositByUuidParams,
+  };
+
+  export { WalletStatus as WalletStatus, type WalletStatusListResponse as WalletStatusListResponse };
+
+  export { APIKeys as APIKeys, type APIKeyListResponse as APIKeyListResponse };
+
+  export {
+    Orders as Orders,
+    type BatchCancelResult as BatchCancelResult,
+    type ClosedOrderState as ClosedOrderState,
+    type OpenOrderState as OpenOrderState,
+    type OrdTypeEnum as OrdTypeEnum,
+    type Order as Order,
+    type SideEnum as SideEnum,
+    type SmpTypeEnum as SmpTypeEnum,
+    type TimeInForceEnum as TimeInForceEnum,
+    type OrderListByUuidsResponse as OrderListByUuidsResponse,
+    type OrderListClosedResponse as OrderListClosedResponse,
+    type OrderRetrieveChanceResponse as OrderRetrieveChanceResponse,
+    type OrdersPageNumberPage as OrdersPageNumberPage,
+    type OrderCreateParams as OrderCreateParams,
+    type OrderRetrieveParams as OrderRetrieveParams,
+    type OrderCancelParams as OrderCancelParams,
+    type OrderCancelAndNewParams as OrderCancelAndNewParams,
+    type OrderCancelByUuidsParams as OrderCancelByUuidsParams,
+    type OrderCancelOpenParams as OrderCancelOpenParams,
+    type OrderListByUuidsParams as OrderListByUuidsParams,
+    type OrderListClosedParams as OrderListClosedParams,
+    type OrderListOpenParams as OrderListOpenParams,
+    type OrderRetrieveChanceParams as OrderRetrieveChanceParams,
+    type OrderTestCreateParams as OrderTestCreateParams,
+  };
+
+  export {
+    Withdraws as Withdraws,
+    type Withdraw as Withdraw,
+    type WithdrawCreateKrwWithdrawalResponse as WithdrawCreateKrwWithdrawalResponse,
+    type WithdrawListCoinAddressesResponse as WithdrawListCoinAddressesResponse,
+    type WithdrawRetrieveChanceResponse as WithdrawRetrieveChanceResponse,
+    type WithdrawsUuidCursorIDPage as WithdrawsUuidCursorIDPage,
+    type WithdrawRetrieveParams as WithdrawRetrieveParams,
+    type WithdrawListParams as WithdrawListParams,
+    type WithdrawCancelWithdrawalParams as WithdrawCancelWithdrawalParams,
+    type WithdrawCreateKrwWithdrawalParams as WithdrawCreateKrwWithdrawalParams,
+    type WithdrawCreateWithdrawalParams as WithdrawCreateWithdrawalParams,
+    type WithdrawRetrieveChanceParams as WithdrawRetrieveChanceParams,
+  };
+
+  export {
+    Deposits as Deposits,
+    type Deposit as Deposit,
+    type DepositAddress as DepositAddress,
+    type DepositCreateCoinAddressResponse as DepositCreateCoinAddressResponse,
+    type DepositListCoinAddressesResponse as DepositListCoinAddressesResponse,
+    type DepositRetrieveChanceResponse as DepositRetrieveChanceResponse,
+    type DepositsUuidCursorIDPage as DepositsUuidCursorIDPage,
+    type DepositRetrieveParams as DepositRetrieveParams,
+    type DepositListParams as DepositListParams,
+    type DepositCreateCoinAddressParams as DepositCreateCoinAddressParams,
+    type DepositDepositKrwParams as DepositDepositKrwParams,
+    type DepositRetrieveChanceParams as DepositRetrieveChanceParams,
+    type DepositRetrieveCoinAddressParams as DepositRetrieveCoinAddressParams,
+  };
+
+  export {
+    TradingPairs as TradingPairs,
+    type TradingPairListResponse as TradingPairListResponse,
+    type TradingPairListParams as TradingPairListParams,
+  };
+
+  export {
+    Tickers as Tickers,
+    type Ticker as Ticker,
+    type TickerListByQuoteCurrenciesResponse as TickerListByQuoteCurrenciesResponse,
+    type TickerListByTradingPairsResponse as TickerListByTradingPairsResponse,
+    type TickerListByQuoteCurrenciesParams as TickerListByQuoteCurrenciesParams,
+    type TickerListByTradingPairsParams as TickerListByTradingPairsParams,
+  };
+
+  export {
+    Orderbooks as Orderbooks,
+    type OrderbookListResponse as OrderbookListResponse,
+    type OrderbookListInstrumentsResponse as OrderbookListInstrumentsResponse,
+    type OrderbookListParams as OrderbookListParams,
+    type OrderbookListInstrumentsParams as OrderbookListInstrumentsParams,
+  };
+
+  export {
+    Trades as Trades,
+    type TradeListResponse as TradeListResponse,
+    type TradeListParams as TradeListParams,
+  };
+
+  export {
+    Candles as Candles,
+    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,
+  };
+
+  export {
+    WsPublic as WsPublic,
+    type ConnectPublicClientEvent as ConnectPublicClientEvent,
+    type ConnectPublicServerEvent as ConnectPublicServerEvent,
+  };
+
+  export {
+    WsPrivate as WsPrivate,
+    type ConnectPrivateClientEvent as ConnectPrivateClientEvent,
+    type ConnectPrivateServerEvent as ConnectPrivateServerEvent,
+  };
+}
+
+function getRuntimeName(): string {
+  if (typeof (globalThis as any).Bun !== 'undefined') return 'bun';
+  if (typeof (globalThis as any).Deno !== 'undefined') return 'deno';
+  return 'node';
+}
+
+function getRuntimeVersion(): string {
+  if (typeof (globalThis as any).Bun !== 'undefined') {
+    return (globalThis as any).Bun.version ?? 'unknown';
+  }
+  if (typeof (globalThis as any).Deno !== 'undefined') {
+    return (globalThis as any).Deno.version?.deno ?? 'unknown';
+  }
+  return typeof process !== 'undefined' ? process.version : 'unknown';
+}