@upbit-official/upbit-sdk 0.9.0 → 1.1.0

package/src/resources/pockets.ts

@@ -0,0 +1,639 @@
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class Pockets extends APIResource {
+  /**
+   * List Pockets
+   *
+   * GET /v1/pockets
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-pockets
+   * - Supported only in Korea.
+   *
+   * Retrieve the UUIDs and names of the main pocket and user-created pockets.
+   *
+   * @example
+   * ```ts
+   * const pockets = await client.pockets.list();
+   * ```
+   */
+  list(options?: RequestOptions): APIPromise<PocketListResponse> {
+    return this._client.get('/v1/pockets', options);
+  }
+
+  /**
+   * List Pocket API Keys
+   *
+   * GET /v1/pockets/api_keys
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-pocket-api-keys
+   * - Supported only in Korea.
+   *
+   * List API keys and related information for each created pocket using main-pocket
+   * API key permissions.
+   *
+   * @example
+   * ```ts
+   * const pocketAPIKeyGroups =
+   *   await client.pockets.listAPIKeys();
+   * ```
+   */
+  listAPIKeys(
+    query: PocketListAPIKeysParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PocketListAPIKeysResponse> {
+    return this._client.get('/v1/pockets/api_keys', { query, ...options });
+  }
+
+  /**
+   * List Transfers
+   *
+   * GET /v1/pockets/transfers
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-transfers
+   * - Supported only in Korea.
+   *
+   * List asset transfer history between pockets that occurred from the sub-pocket
+   * using sub-pocket API key permissions.
+   *
+   * @example
+   * ```ts
+   * const pocketTransfers =
+   *   await client.pockets.listTransfers();
+   * ```
+   */
+  listTransfers(
+    query: PocketListTransfersParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PocketListTransfersResponse> {
+    return this._client.get('/v1/pockets/transfers', { query, ...options });
+  }
+
+  /**
+   * List Universal Transfers
+   *
+   * GET /v1/pockets/universal_transfers
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-universal-transfers
+   * - Supported only in Korea.
+   *
+   * List asset transfer history between pockets, such as main pocket to sub-pocket,
+   * using main-pocket API key permissions.
+   *
+   * @example
+   * ```ts
+   * const pocketTransfers =
+   *   await client.pockets.listUniversalTransfers();
+   * ```
+   */
+  listUniversalTransfers(
+    query: PocketListUniversalTransfersParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PocketListUniversalTransfersResponse> {
+    return this._client.get('/v1/pockets/universal_transfers', { query, ...options });
+  }
+
+  /**
+   * Get Sub-Pocket Balance
+   *
+   * GET /v1/pockets/assets
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/get-sub-pocket-balance
+   * - Supported only in Korea.
+   *
+   * Retrieve balances for a specific sub-pocket using main-pocket API key
+   * permissions.
+   *
+   * @example
+   * ```ts
+   * const pocketBalances = await client.pockets.retrieveBalance(
+   *   { uuid: 'uuid' },
+   * );
+   * ```
+   */
+  retrieveBalance(
+    query: PocketRetrieveBalanceParams,
+    options?: RequestOptions,
+  ): APIPromise<PocketRetrieveBalanceResponse> {
+    return this._client.get('/v1/pockets/assets', { query, ...options });
+  }
+
+  /**
+   * Transfer
+   *
+   * POST /v1/pockets/transfers
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/transfer
+   * - Supported only in Korea.
+   *
+   * Request an asset transfer between pockets, such as sub-pocket to sub-pocket,
+   * using sub-pocket API key permissions.
+   *
+   * @example
+   * ```ts
+   * const pocketTransfer = await client.pockets.transfer({
+   *   amount: '10.00',
+   *   currency: 'XRP',
+   *   to: '9ca023a5-851b-4fec-9f0a-48cd83c2eaae',
+   *   identifier: 'unique_transfer_id_20260531_01',
+   * });
+   * ```
+   */
+  transfer(body: PocketTransferParams, options?: RequestOptions): APIPromise<PocketTransfer> {
+    return this._client.post('/v1/pockets/transfers', { body, ...options });
+  }
+
+  /**
+   * Universal Transfer
+   *
+   * POST /v1/pockets/universal_transfers
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/universal-transfer
+   * - Supported only in Korea.
+   *
+   * Request an asset transfer between pockets, such as main pocket to sub-pocket,
+   * using main-pocket API key permissions.
+   *
+   * @example
+   * ```ts
+   * const pocketTransfer =
+   *   await client.pockets.universalTransfer({
+   *     amount: '10.00',
+   *     currency: 'XRP',
+   *     to: '9ca023a5-851b-4fec-9f0a-48cd83c2eaae',
+   *     from: '9ca023a5-851b-4fec-9f0a-48cd83c2eaae',
+   *     identifier: 'unique_transfer_id_20260531_01',
+   *   });
+   * ```
+   */
+  universalTransfer(
+    body: PocketUniversalTransferParams,
+    options?: RequestOptions,
+  ): APIPromise<PocketTransfer> {
+    return this._client.post('/v1/pockets/universal_transfers', { body, ...options });
+  }
+}
+
+export interface Pocket {
+  /**
+   * Pocket name.
+   */
+  name: string;
+
+  /**
+   * Pocket type.
+   *
+   * - `main`: Main pocket
+   * - `user_spot_trading`: User-created pocket
+   */
+  type: PocketType;
+
+  /**
+   * Pocket UUID.
+   */
+  uuid: string;
+}
+
+export interface PocketAPIKey {
+  /**
+   * Access key of the API key.
+   */
+  access_key: string;
+
+  /**
+   * List of IP addresses allowed to make API requests.
+   */
+  allowed_ips: Array<string>;
+
+  /**
+   * Timestamp when the API key was created.
+   *
+   * [Format] yyyy-MM-dd'T'HH:mm:ss+09:00
+   */
+  created_at: string;
+
+  /**
+   * Timestamp when the API key expires.
+   *
+   * [Format] yyyy-MM-dd'T'HH:mm:ss+09:00
+   */
+  expired_at: string;
+
+  /**
+   * List of access permissions granted to the API key.
+   */
+  permissions: Array<PocketAPIKeyPermission>;
+}
+
+export interface PocketAPIKeyGroup {
+  /**
+   * List of API keys issued for the pocket.
+   */
+  keys: Array<PocketAPIKey>;
+
+  /**
+   * Pocket UUID.
+   */
+  uuid: string;
+}
+
+/**
+ * Access permission granted to the API key.
+ *
+ * - `view_account`: View assets/accounts
+ * - `view_orders`: View order history
+ * - `make_orders`: Create and execute orders
+ * - `view_withdrawals`: View withdrawal history
+ * - `withdraw`: Withdraw digital assets/KRW
+ * - `view_deposits`: View deposit history
+ * - `deposit`: Create deposit addresses and deposits
+ * - `transfer`: Transfer assets between pockets
+ * - `manage_pockets`: Create and manage pockets
+ */
+export type PocketAPIKeyPermission =
+  | 'view_account'
+  | 'view_orders'
+  | 'make_orders'
+  | 'view_withdrawals'
+  | 'withdraw'
+  | 'view_deposits'
+  | 'deposit'
+  | 'transfer'
+  | 'manage_pockets';
+
+export interface PocketBalance {
+  /**
+   * Average buy price of the asset.
+   */
+  avg_buy_price: string;
+
+  /**
+   * Indicates whether the average buy price has been modified.
+   */
+  avg_buy_price_modified: boolean;
+
+  /**
+   * Available quantity or amount for orders.
+   *
+   * - Digital assets: quantity
+   * - Fiat currency (KRW): amount
+   */
+  balance: string;
+
+  /**
+   * Currency code of the held asset.
+   *
+   * [Example] KRW, BTC, ETH
+   */
+  currency: string;
+
+  /**
+   * Balance locked by withdrawals, pending order execution, or similar operations.
+   */
+  locked: string;
+
+  /**
+   * Currency unit used as the basis for `avg_buy_price`.
+   *
+   * [Example] KRW, BTC, USDT
+   */
+  unit_currency: string;
+}
+
+export interface PocketTransfer {
+  /**
+   * Transferred asset quantity.
+   */
+  amount: string;
+
+  /**
+   * Timestamp when the request was created.
+   */
+  created_at: string;
+
+  /**
+   * Transferred asset code.
+   *
+   * [Example] KRW, BTC, ETH
+   */
+  currency: string;
+
+  /**
+   * UUID of the pocket that sent the asset.
+   */
+  from: string;
+
+  /**
+   * Client-provided identifier for the asset transfer request. Returns null if not
+   * specified.
+   */
+  identifier: string | null;
+
+  /**
+   * Asset transfer request state.
+   *
+   * - `submitted`: Submitted
+   * - `processing`: Processing
+   * - `done`: Completed
+   * - `failed`: Failed
+   */
+  state: PocketTransferState;
+
+  /**
+   * UUID of the pocket that received the asset.
+   */
+  to: string;
+
+  /**
+   * UUID identifying the asset transfer request.
+   */
+  uuid: string;
+}
+
+/**
+ * Transfer direction.
+ *
+ * - `in`: Transfers into the sub-pocket
+ * - `out`: Transfers out of the sub-pocket
+ * - `all`: Transfers in all directions
+ */
+export type PocketTransferDirection = 'in' | 'out' | 'all';
+
+/**
+ * Asset transfer request state.
+ *
+ * - `submitted`: Submitted
+ * - `processing`: Processing
+ * - `done`: Completed
+ * - `failed`: Failed
+ */
+export type PocketTransferState = 'submitted' | 'processing' | 'done' | 'failed';
+
+/**
+ * Pocket type.
+ *
+ * - `main`: Main pocket
+ * - `user_spot_trading`: User-created pocket
+ */
+export type PocketType = 'main' | 'user_spot_trading';
+
+export type PocketListResponse = Array<Pocket>;
+
+export type PocketListAPIKeysResponse = Array<PocketAPIKeyGroup>;
+
+export type PocketListTransfersResponse = Array<PocketTransfer>;
+
+export type PocketListUniversalTransfersResponse = Array<PocketTransfer>;
+
+export type PocketRetrieveBalanceResponse = Array<PocketBalance>;
+
+export interface PocketListAPIKeysParams {
+  /**
+   * Whether to include expired API keys in the results.
+   */
+  include_expired?: boolean;
+
+  /**
+   * Array of pocket UUIDs to query.
+   *
+   * [Example] uuids[]=uuid1&uuids[]=uuid2
+   */
+  uuids?: Array<string>;
+}
+
+export interface PocketListTransfersParams {
+  /**
+   * Asset code to query.
+   */
+  currency?: string;
+
+  /**
+   * Transfer direction.
+   *
+   * - `in`: Transfers into the sub-pocket
+   * - `out`: Transfers out of the sub-pocket
+   * - `all`: Transfers in all directions
+   */
+  direction?: PocketTransferDirection;
+
+  /**
+   * End time of the query period. Retrieves records created from `start_time` to the
+   * specified time.
+   *
+   * Default: Current time. Limit: Maximum query range is 7 days. Allowed format: ISO
+   * 8601 with timezone or millisecond timestamp.
+   */
+  end_time?: string;
+
+  /**
+   * List of client-provided identifiers specified when requesting transfers.
+   *
+   * [Example] identifiers[]=id1&identifiers[]=id2
+   *
+   * Limit: Up to 20 items.
+   */
+  identifiers?: Array<string>;
+
+  /**
+   * Number of results to request (default 20, max 100).
+   */
+  limit?: number;
+
+  /**
+   * Sort order. `asc` for oldest first, `desc` for newest first.
+   */
+  order_by?: 'asc' | 'desc';
+
+  /**
+   * Start time of the query period. Retrieves records created from the specified
+   * time to `end_time`.
+   *
+   * Allowed format: ISO 8601 with timezone or millisecond timestamp.
+   */
+  start_time?: string;
+
+  /**
+   * Asset transfer request states. Returns only transfers in the specified states.
+   * If omitted, returns transfers in all states.
+   *
+   * [Example] states[]=done&states[]=failed
+   */
+  states?: Array<PocketTransferState>;
+
+  /**
+   * List of UUIDs identifying asset transfer requests. Returns only transfers
+   * matching the specified UUIDs.
+   *
+   * [Example] uuids[]=uuid1&uuids[]=uuid2
+   *
+   * Limit: Up to 20 items.
+   */
+  uuids?: Array<string>;
+}
+
+export interface PocketListUniversalTransfersParams {
+  /**
+   * Asset code to query.
+   */
+  currency?: string;
+
+  /**
+   * End time of the query period. Retrieves records created from `start_time` to the
+   * specified time.
+   *
+   * Default: Current time. Limit: Maximum query range is 7 days. Allowed format: ISO
+   * 8601 with timezone or millisecond timestamp.
+   */
+  end_time?: string;
+
+  /**
+   * UUID of the pocket that sent the asset.
+   */
+  from?: string;
+
+  /**
+   * List of client-provided identifiers specified when requesting transfers.
+   *
+   * [Example] identifiers[]=id1&identifiers[]=id2
+   *
+   * Limit: Up to 20 items.
+   */
+  identifiers?: Array<string>;
+
+  /**
+   * Number of results to request (default 20, max 100).
+   */
+  limit?: number;
+
+  /**
+   * Sort order. `asc` for oldest first, `desc` for newest first.
+   */
+  order_by?: 'asc' | 'desc';
+
+  /**
+   * Start time of the query period. Retrieves records created from the specified
+   * time to `end_time`.
+   *
+   * Allowed format: ISO 8601 with timezone or millisecond timestamp.
+   */
+  start_time?: string;
+
+  /**
+   * Asset transfer request states. Available values: `submitted`, `processing`,
+   * `done`, `failed`. Returns only transfers in the specified states. If omitted,
+   * returns transfers in all states.
+   *
+   * [Example] states[]=done&states[]=failed
+   */
+  states?: Array<PocketTransferState>;
+
+  /**
+   * UUID of the pocket that received the asset.
+   */
+  to?: string;
+
+  /**
+   * List of UUIDs identifying asset transfer requests. Returns only transfers
+   * matching the specified UUIDs.
+   *
+   * [Example] uuids[]=uuid1&uuids[]=uuid2
+   *
+   * Limit: Up to 20 items.
+   */
+  uuids?: Array<string>;
+}
+
+export interface PocketRetrieveBalanceParams {
+  /**
+   * UUID of the sub-pocket to query.
+   */
+  uuid: string;
+}
+
+export interface PocketTransferParams {
+  /**
+   * Asset quantity to transfer.
+   */
+  amount: string;
+
+  /**
+   * Asset code to transfer.
+   *
+   * [Example] KRW, BTC, ETH
+   */
+  currency: string;
+
+  /**
+   * UUID of the receiving pocket.
+   */
+  to: string;
+
+  /**
+   * Client-provided identifier for the asset transfer request. Returns null if not
+   * specified.
+   *
+   * Allowed format: 1 to 64 letters, numbers, underscores (\_), periods (.), or
+   * hyphens (-).
+   */
+  identifier?: string;
+}
+
+export interface PocketUniversalTransferParams {
+  /**
+   * Asset quantity to transfer.
+   */
+  amount: string;
+
+  /**
+   * Asset code to transfer.
+   *
+   * [Example] KRW, BTC, ETH
+   */
+  currency: string;
+
+  /**
+   * UUID of the receiving pocket.
+   */
+  to: string;
+
+  /**
+   * UUID of the sending pocket. If omitted, defaults to the pocket associated with
+   * the API key used for the request.
+   */
+  from?: string;
+
+  /**
+   * Client-provided identifier for the asset transfer request. Returns null if not
+   * specified.
+   *
+   * Allowed format: 1 to 64 letters, numbers, underscores (\_), periods (.), or
+   * hyphens (-).
+   */
+  identifier?: string;
+}
+
+export declare namespace Pockets {
+  export {
+    type Pocket as Pocket,
+    type PocketAPIKey as PocketAPIKey,
+    type PocketAPIKeyGroup as PocketAPIKeyGroup,
+    type PocketAPIKeyPermission as PocketAPIKeyPermission,
+    type PocketBalance as PocketBalance,
+    type PocketTransfer as PocketTransfer,
+    type PocketTransferDirection as PocketTransferDirection,
+    type PocketTransferState as PocketTransferState,
+    type PocketType as PocketType,
+    type PocketListResponse as PocketListResponse,
+    type PocketListAPIKeysResponse as PocketListAPIKeysResponse,
+    type PocketListTransfersResponse as PocketListTransfersResponse,
+    type PocketListUniversalTransfersResponse as PocketListUniversalTransfersResponse,
+    type PocketRetrieveBalanceResponse as PocketRetrieveBalanceResponse,
+    type PocketListAPIKeysParams as PocketListAPIKeysParams,
+    type PocketListTransfersParams as PocketListTransfersParams,
+    type PocketListUniversalTransfersParams as PocketListUniversalTransfersParams,
+    type PocketRetrieveBalanceParams as PocketRetrieveBalanceParams,
+    type PocketTransferParams as PocketTransferParams,
+    type PocketUniversalTransferParams as PocketUniversalTransferParams,
+  };
+}

package/src/resources/tickers.ts

@@ -1,4 +1,3 @@
-
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
@@ -11,6 +10,9 @@ export class Tickers extends APIResource {
    *
    * - docs(kr): https://docs.upbit.com/kr/reference/list-quote-tickers
    * - docs(global): https://global-docs.upbit.com/reference/list-quote-tickers
+   *
+   * Retrieves current price information of all pairs in the specified market(quote
+   * currency).
    */
   listByQuoteCurrencies(
     query: TickerListByQuoteCurrenciesParams,
@@ -26,6 +28,9 @@ export class Tickers extends APIResource {
    *
    * - docs(kr): https://docs.upbit.com/kr/reference/list-tickers
    * - docs(global): https://global-docs.upbit.com/reference/list-tickers
+   *
+   * Retrieves the current price for the specified pair. Returns the ticker snapshot
+   * of the pair at the time of the request.
    */
   listByTradingPairs(
     query: TickerListByTradingPairsParams,

package/src/resources/trades.ts

@@ -1,16 +1,17 @@
-
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 export class Trades extends APIResource {
   /**
-   * Recent Trades History
+   * List Pair Trades
    *
    * GET /v1/trades/ticks
    *
-   * - docs(kr): https://docs.upbit.com/kr/reference/recent-trades-history
-   * - docs(global): https://global-docs.upbit.com/reference/recent-trades-history
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-pair-trades
+   * - docs(global): https://global-docs.upbit.com/reference/list-pair-trades
+   *
+   * Retrieves recent trades for the specified pair.
    */
   list(query: TradeListParams, options?: RequestOptions): APIPromise<TradeListResponse> {
     return this._client.get('/v1/trades/ticks', { query, ...options, __security: {} });

package/src/resources/trading-pairs.ts

@@ -1,4 +1,3 @@
-
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
@@ -11,6 +10,8 @@ export class TradingPairs extends APIResource {
    *
    * - docs(kr): https://docs.upbit.com/kr/reference/list-trading-pairs
    * - docs(global): https://global-docs.upbit.com/reference/list-trading-pairs
+   *
+   * Retrieves the list of all trading pairs supported by Upbit.
    */
   list(
     query: TradingPairListParams | null | undefined = {},