@upbit-official/upbit-sdk 0.9.0

package/src/resources/withdraws.ts

@@ -0,0 +1,734 @@
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { PagePromise, UuidCursorIDPage, type UuidCursorIDPageParams } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+
+export class Withdraws extends APIResource {
+  /**
+   * Get Withdrawal
+   *
+   * GET /v1/withdraw
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/get-withdrawal
+   * - docs(global): https://global-docs.upbit.com/reference/get-withdrawal
+   *
+   * @example
+   * ```ts
+   * const withdraw = await client.withdraws.retrieve();
+   * ```
+   */
+  retrieve(
+    query: WithdrawRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Withdraw> {
+    return this._client.get('/v1/withdraw', { query, ...options });
+  }
+
+  /**
+   * List Withdrawals
+   *
+   * GET /v1/withdraws
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-withdrawals
+   * - docs(global): https://global-docs.upbit.com/reference/list-withdrawals
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const withdraw of client.withdraws.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: WithdrawListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<WithdrawsUuidCursorIDPage, Withdraw> {
+    return this._client.getAPIList('/v1/withdraws', UuidCursorIDPage<Withdraw>, { query, ...options });
+  }
+
+  /**
+   * Cancel Withdrawal
+   *
+   * DELETE /v1/withdraws/coin
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/cancel-withdrawal
+   * - docs(global): https://global-docs.upbit.com/reference/cancel-withdrawal
+   *
+   * @example
+   * ```ts
+   * const withdraw = await client.withdraws.cancelWithdrawal({
+   *   uuid: '9ca023a5-851b-4fec-9f0a-48cd83c2eaae',
+   * });
+   * ```
+   */
+  cancelWithdrawal(params: WithdrawCancelWithdrawalParams, options?: RequestOptions): APIPromise<Withdraw> {
+    const { uuid } = params;
+    return this._client.delete('/v1/withdraws/coin', { query: { uuid }, ...options });
+  }
+
+  /**
+   * Withdraw KRW
+   *
+   * POST /v1/withdraws/krw
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/withdraw-krw
+   * - docs(global): https://global-docs.upbit.com/reference/withdraw-krw
+   *
+   * @example
+   * ```ts
+   * const response = await client.withdraws.createKrwWithdrawal(
+   *   { amount: '10000', two_factor_type: 'naver' },
+   * );
+   * ```
+   */
+  createKrwWithdrawal(
+    body: WithdrawCreateKrwWithdrawalParams,
+    options?: RequestOptions,
+  ): APIPromise<WithdrawCreateKrwWithdrawalResponse> {
+    return this._client.post('/v1/withdraws/krw', { body, ...options });
+  }
+
+  /**
+   * Withdraw Digital Asset
+   *
+   * POST /v1/withdraws/coin
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/withdraw
+   * - docs(global): https://global-docs.upbit.com/reference/withdraw
+   *
+   * @example
+   * ```ts
+   * const withdraw = await client.withdraws.createWithdrawal({
+   *   address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
+   *   amount: '0.01',
+   *   currency: 'BTC',
+   *   net_type: 'BTC',
+   * });
+   * ```
+   */
+  createWithdrawal(body: WithdrawCreateWithdrawalParams, options?: RequestOptions): APIPromise<Withdraw> {
+    return this._client.post('/v1/withdraws/coin', { body, ...options });
+  }
+
+  /**
+   * List Withdrawal Allowed Addresses
+   *
+   * GET /v1/withdraws/coin_addresses
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-withdrawal-addresses
+   * - docs(global):
+   *   https://global-docs.upbit.com/reference/list-withdrawal-addresses
+   *
+   * @example
+   * ```ts
+   * const response = await client.withdraws.listCoinAddresses();
+   * ```
+   */
+  listCoinAddresses(options?: RequestOptions): APIPromise<WithdrawListCoinAddressesResponse> {
+    return this._client.get('/v1/withdraws/coin_addresses', options);
+  }
+
+  /**
+   * Get Available Withdrawal Information
+   *
+   * GET /v1/withdraws/chance
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/available-withdrawal-information
+   * - docs(global):
+   *   https://global-docs.upbit.com/reference/available-withdrawal-information
+   *
+   * @example
+   * ```ts
+   * const response = await client.withdraws.retrieveChance({
+   *   currency: 'BTC',
+   *   net_type: 'BTC',
+   * });
+   * ```
+   */
+  retrieveChance(
+    query: WithdrawRetrieveChanceParams,
+    options?: RequestOptions,
+  ): APIPromise<WithdrawRetrieveChanceResponse> {
+    return this._client.get('/v1/withdraws/chance', { query, ...options });
+  }
+}
+
+export type WithdrawsUuidCursorIDPage = UuidCursorIDPage<Withdraw>;
+
+export interface Withdraw {
+  /**
+   * Amount of the asset to withdraw.
+   */
+  amount: string;
+
+  /**
+   * Timestamp when the withdrawal was created.
+   */
+  created_at: string;
+
+  /**
+   * Currency code to be queried.
+   */
+  currency: string;
+
+  /**
+   * Withdrawal fee.
+   */
+  fee: string;
+
+  /**
+   * Whether the withdrawal can be cancelled.
+   */
+  is_cancelable: boolean | null;
+
+  /**
+   * Withdrawal network type.
+   *
+   * Blockchain network identifier used by Upbit.
+   *
+   * [Example] "ETH", "TRX", "SOL"
+   */
+  net_type: string | null;
+
+  /**
+   * Withdrawal processing state.
+   *
+   * - `WAITING`: Waiting
+   * - `PROCESSING`: Processing
+   * - `DONE`: Completed
+   * - `FAILED`: Failed
+   * - `CANCELLED`: Cancelled
+   * - `REJECTED`: Rejected
+   */
+  state: 'WAITING' | 'PROCESSING' | 'DONE' | 'FAILED' | 'CANCELLED' | 'REJECTED';
+
+  /**
+   * Withdrawal transaction type.
+   *
+   * - `default`: Standard withdrawal
+   * - `internal`: Internal (instant) withdrawal
+   */
+  transaction_type: 'default' | 'internal';
+
+  /**
+   * Transaction ID.
+   */
+  txid: string | null;
+
+  /**
+   * Transaction type.
+   */
+  type: string;
+
+  /**
+   * Unique identifier of the withdrawal.
+   */
+  uuid: string;
+
+  /**
+   * Timestamp when the withdrawal was completed. Returns null if not yet completed.
+   */
+  done_at?: string | null;
+}
+
+export interface WithdrawCreateKrwWithdrawalResponse {
+  /**
+   * Amount of the asset to withdraw.
+   */
+  amount: string;
+
+  /**
+   * Timestamp when the withdrawal was created.
+   */
+  created_at: string;
+
+  /**
+   * Currency code to be queried.
+   */
+  currency: string;
+
+  /**
+   * Withdrawal fee.
+   */
+  fee: string;
+
+  /**
+   * Whether the withdrawal can be cancelled.
+   */
+  is_cancelable: boolean | null;
+
+  /**
+   * Withdrawal network type.
+   *
+   * Blockchain network identifier used by Upbit.
+   *
+   * [Example] "ETH", "TRX", "SOL"
+   */
+  net_type: string | null;
+
+  /**
+   * Withdrawal processing state.
+   *
+   * - `waiting`: Waiting
+   * - `processing`: Processing
+   * - `done`: Completed
+   * - `failed`: Failed
+   * - `cancelled`: Cancelled
+   * - `rejected`: Rejected
+   */
+  state: 'waiting' | 'processing' | 'done' | 'failed' | 'cancelled' | 'rejected';
+
+  /**
+   * Withdrawal transaction type.
+   *
+   * - `default`: Standard withdrawal
+   * - `internal`: Internal (instant) withdrawal
+   */
+  transaction_type: 'default' | 'internal';
+
+  /**
+   * Transaction ID.
+   */
+  txid: string | null;
+
+  /**
+   * Transaction type.
+   */
+  type: string;
+
+  /**
+   * Unique identifier of the withdrawal.
+   */
+  uuid: string;
+
+  /**
+   * Timestamp when the withdrawal was completed. Returns null if not yet completed.
+   */
+  done_at?: string | null;
+}
+
+export type WithdrawListCoinAddressesResponse =
+  Array<WithdrawListCoinAddressesResponse.WithdrawListCoinAddressesResponseItem>;
+
+export namespace WithdrawListCoinAddressesResponse {
+  export interface WithdrawListCoinAddressesResponseItem {
+    /**
+     * Currency code of the digital asset to withdraw.
+     */
+    currency: string;
+
+    /**
+     * Withdrawal network type.
+     *
+     * Blockchain network identifier used by Upbit. The `net_type` parameter in
+     * withdrawal requests must match this value.
+     *
+     * [Example] "ETH", "TRX", "SOL"
+     */
+    net_type: string;
+
+    /**
+     * Withdrawal network name displayed to users.
+     *
+     * [Example] "Ethereum", "Bitcoin", "Tron", "Solana"
+     */
+    network_name: string;
+
+    /**
+     * Recipient address for digital asset withdrawal.
+     *
+     * Only addresses registered in the allowed withdrawal address list can be used.
+     */
+    withdraw_address: string;
+
+    /**
+     * Company name of the entity receiving the withdrawn assets.
+     */
+    beneficiary_company_name?: string | null;
+
+    /**
+     * Name of the wallet owner.
+     *
+     * Name of the individual or corporate representative receiving the withdrawn
+     * assets. Returned only for exchange wallets; null for personal wallets.
+     */
+    beneficiary_name?: string;
+
+    /**
+     * Account holder type.
+     *
+     * - `individual`: Personal wallet
+     * - `corporate`: Corporate wallet
+     */
+    beneficiary_type?: string | null;
+
+    /**
+     * Name of the exchange where the withdrawal address is registered.
+     *
+     * [Example] "Binance", "Bybit"
+     */
+    exchange_name?: string | null;
+
+    /**
+     * Secondary withdrawal address (Destination Tag, Memo, or Message). Some digital
+     * assets require a secondary address along with the primary address.
+     */
+    secondary_address?: string | null;
+
+    /**
+     * Personal wallet type.
+     *
+     * [Example] "MetaMask"
+     */
+    wallet_type?: string | null;
+  }
+}
+
+export interface WithdrawRetrieveChanceResponse {
+  /**
+   * Asset balance information.
+   */
+  account: WithdrawRetrieveChanceResponse.Account;
+
+  /**
+   * Currency information.
+   */
+  currency: WithdrawRetrieveChanceResponse.Currency;
+
+  /**
+   * User security level information.
+   */
+  member_level: WithdrawRetrieveChanceResponse.MemberLevel;
+
+  /**
+   * Withdrawal limit information.
+   */
+  withdraw_limit: WithdrawRetrieveChanceResponse.WithdrawLimit;
+}
+
+export namespace WithdrawRetrieveChanceResponse {
+  /**
+   * Asset balance information.
+   */
+  export interface Account {
+    /**
+     * 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 amount or volume for orders.
+     */
+    balance: string;
+
+    /**
+     * Currency code to be queried.
+     */
+    currency: string;
+
+    /**
+     * Amount or quantity locked by pending orders or withdrawals.
+     */
+    locked: string;
+
+    /**
+     * Currency unit used as the basis for avg_buy_price.
+     */
+    unit_currency: string;
+  }
+
+  /**
+   * Currency information.
+   */
+  export interface Currency {
+    /**
+     * Currency code.
+     */
+    code: string;
+
+    /**
+     * Whether this is a digital asset.
+     */
+    is_coin: boolean;
+
+    /**
+     * Whether deposit/withdrawal has been supported for this asset.
+     *
+     * - `working`: Has been supported
+     * - `unsupported`: Never supported
+     */
+    wallet_state: 'working' | 'unsupported';
+
+    /**
+     * Current deposit/withdrawal availability. 'deposit' if deposits are available,
+     * 'withdraw' if withdrawals are available. Empty list means neither is available.
+     */
+    wallet_support: Array<string>;
+
+    /**
+     * Withdrawal fee.
+     */
+    withdraw_fee: string;
+  }
+
+  /**
+   * User security level information.
+   */
+  export interface MemberLevel {
+    /**
+     * Whether bank account is verified.
+     */
+    bank_account_verified: boolean;
+
+    /**
+     * Whether email is verified.
+     */
+    email_verified: boolean;
+
+    /**
+     * Fee level.
+     */
+    fee_level: number;
+
+    /**
+     * Whether identity is verified.
+     */
+    identity_auth_verified: boolean;
+
+    /**
+     * Whether the account is locked.
+     */
+    locked: boolean;
+
+    /**
+     * Security level.
+     */
+    security_level: number;
+
+    /**
+     * Whether two-factor authentication is enabled.
+     */
+    two_factor_auth_verified: boolean;
+
+    /**
+     * Whether the wallet (withdrawal) is locked.
+     */
+    wallet_locked: boolean;
+  }
+
+  /**
+   * Withdrawal limit information.
+   */
+  export interface WithdrawLimit {
+    /**
+     * Currency code to be queried.
+     */
+    currency: string;
+
+    /**
+     * Reference fiat currency.
+     */
+    fiat_currency: string;
+
+    /**
+     * Integrated remaining daily withdrawal limit (in fiat currency).
+     */
+    remaining_daily_fiat: string;
+
+    /**
+     * Whether withdrawal is currently supported.
+     *
+     * - To check current availability, refer to currency.wallet_support for the
+     *   'withdraw' value.
+     */
+    can_withdraw?: boolean;
+
+    /**
+     * Decimal precision for withdrawal amount/volume.
+     */
+    fixed?: number;
+
+    /**
+     * Minimum withdrawal amount or volume.
+     */
+    minimum?: string;
+
+    /**
+     * Amount restricted due to the withdrawal delay policy.
+     */
+    withdraw_delayed_fiat?: string;
+  }
+}
+
+export interface WithdrawRetrieveParams {
+  /**
+   * Currency code filter. If not specified, the latest withdrawal is returned.
+   */
+  currency?: string;
+
+  /**
+   * Transaction ID of the withdrawal to query.
+   *
+   * If neither uuid nor txid is provided, the latest withdrawal is returned.
+   */
+  txid?: string;
+
+  /**
+   * UUID of the withdrawal to query.
+   *
+   * If neither uuid nor txid is provided, the latest withdrawal is returned.
+   */
+  uuid?: string;
+}
+
+export interface WithdrawListParams extends UuidCursorIDPageParams {
+  /**
+   * Currency code filter. If not specified, all currencies are returned.
+   */
+  currency?: string;
+
+  /**
+   * Cursor for pagination. Enter a "uuid" from the response to retrieve "limit"
+   * withdrawals after that timestamp.
+   */
+  from?: string;
+
+  /**
+   * Sort order. "desc" (newest first) or "asc" (oldest first). Default is "desc".
+   */
+  order_by?: 'asc' | 'desc';
+
+  /**
+   * Page number for pagination. Default is 1.
+   */
+  page?: number;
+
+  /**
+   * Withdrawal state filter.
+   *
+   * - `WAITING`: Waiting
+   * - `PROCESSING`: Processing
+   * - `DONE`: Completed
+   * - `FAILED`: Failed
+   * - `CANCELLED`: Cancelled
+   * - `REJECTED`: Rejected
+   */
+  state?: 'WAITING' | 'PROCESSING' | 'DONE' | 'FAILED' | 'CANCELLED' | 'REJECTED';
+
+  /**
+   * List of transaction IDs to query. Maximum 100. Cannot be used together with
+   * uuids.
+   *
+   * [Example] txids[]=txid1&txids[]=txid2
+   */
+  txids?: Array<string>;
+
+  /**
+   * List of UUIDs to query. Maximum 100. Cannot be used together with txids.
+   *
+   * [Example] uuids[]=uuid1&uuids[]=uuid2
+   */
+  uuids?: Array<string>;
+}
+
+export interface WithdrawCancelWithdrawalParams {
+  /**
+   * UUID of the withdrawal to cancel.
+   */
+  uuid: string;
+}
+
+export interface WithdrawCreateKrwWithdrawalParams {
+  /**
+   * KRW amount to withdraw.
+   *
+   * Must be a numeric string.
+   */
+  amount: string;
+
+  /**
+   * Two-factor authentication method for KRW transactions.
+   *
+   * - `kakao`: Kakao authentication
+   * - `naver`: Naver authentication
+   * - `hana`: Hana certificate authentication
+   */
+  two_factor_type: 'kakao' | 'naver' | 'hana';
+}
+
+export interface WithdrawCreateWithdrawalParams {
+  /**
+   * Recipient address for digital asset withdrawal.
+   *
+   * Only addresses registered in the allowed withdrawal address list can be used.
+   */
+  address: string;
+
+  /**
+   * Amount of the asset to withdraw.
+   *
+   * Must be a numeric string.
+   */
+  amount: string;
+
+  /**
+   * Currency code of the digital asset to withdraw.
+   */
+  currency: string;
+
+  /**
+   * Check the allowed withdrawal addresses API response to find the available
+   * "net_type" value for each address.
+   */
+  net_type: string;
+
+  /**
+   * Secondary withdrawal address (Destination Tag, Memo, or Message). If the
+   * recipient address includes a secondary address, this field must be included.
+   */
+  secondary_address?: string | null;
+
+  /**
+   * Withdrawal transaction type.
+   *
+   * - `default`: Standard withdrawal
+   * - `internal`: Internal (instant) withdrawal
+   */
+  transaction_type?: 'default' | 'internal';
+}
+
+export interface WithdrawRetrieveChanceParams {
+  /**
+   * Currency code to query withdrawal availability for.
+   */
+  currency: string;
+
+  /**
+   * Blockchain network identifier for digital asset withdrawal. Required for digital
+   * assets.
+   */
+  net_type: string;
+}
+
+export declare namespace Withdraws {
+  export {
+    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,
+  };
+}