Retrieve Spot Sub-Account List - Balance Details (V2) (Implementation)

Retrieves paginated Spot sub-account information from KuCoin asynchronously, aggregating balance details into a single data.table. This internal function is designed for use within an R6 class and is not intended for direct end-user consumption.

Usage

get_subaccount_spot_v2_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  page_size = 100,
  max_pages = Inf,
  .__coro_env_parent__ = <environment>
)

Arguments

keys

List containing API configuration parameters from get_api_keys(), including:

• api_key: Character string; your KuCoin API key.

• api_secret: Character string; your KuCoin API secret.

• api_passphrase: Character string; your KuCoin API passphrase.

• key_version: Character string; API key version (e.g., "2"). Defaults to get_api_keys().

base_url

Character string representing the base URL for the API. Defaults to get_base_url().

page_size

Integer specifying the number of results per page (minimum 10, maximum 100). Defaults to 100.

max_pages

Numeric specifying the maximum number of pages to fetch (defaults to Inf, fetching all available pages).

Value

Promise resolving to a data.table containing aggregated sub-account balance information, with columns including:

• subUserId (character): Sub-account user ID.

• subName (character): Sub-account name.

• accountType (character): Type of account (e.g., "mainAccounts", "tradeAccounts", "marginAccounts", "tradeHFAccounts").

• currency (character): Currency code.

• balance (numeric): Total balance.

• available (numeric): Amount available for trading or withdrawal.

• holds (numeric): Amount locked or held.

• baseCurrency (character): Base currency code.

• baseCurrencyPrice (numeric): Price of the base currency.

• baseAmount (numeric): Amount in the base currency.

• tag (character): Tag associated with the account.

Details

Workflow Overview

1. Pagination Initialisation: Sets an initial query with currentPage = 1 and the specified page_size.

2. Page Fetching: Defines an asynchronous helper function (fetch_page) to send a GET request for a given page, constructing the URL with current query parameters and authentication headers.

3. Automatic Pagination: Leverages auto_paginate to repeatedly call fetch_page, aggregating results until all pages are retrieved or max_pages is reached.

4. Aggregation: Processes each sub-account's account type arrays, converting them into data.tables with an added accountType column, and combines them into a single data.table with subUserId and subName.

API Endpoint

GET https://api.kucoin.com/api/v2/sub-accounts

Usage

Utilised internally to provide detailed balance information for all sub-accounts associated with a KuCoin master account.

Official Documentation

KuCoin Get Sub-Account List - Spot Balance (V2)

Raw Response Schema:

• code (string): Status code, where "200000" indicates success.

• data (object): Contains pagination metadata and an items array with sub-account details.

Example JSON response:

{
    "code": "200000",
    "data": {
        "currentPage": 1,
        "pageSize": 10,
        "totalNum": 3,
        "totalPage": 1,
        "items": [
            {
                "subUserId": "63743f07e0c5230001761d08",
                "subName": "testapi6",
                "mainAccounts": [
                    {
                        "currency": "USDT",
                        "balance": "0.01",
                        "available": "0.01",
                        "holds": "0",
                        "baseCurrency": "BTC",
                        "baseCurrencyPrice": "62514.5",
                        "baseAmount": "0.00000015",
                        "tag": "DEFAULT"
                    }
                ],
                "tradeAccounts": [
                    {
                        "currency": "USDT",
                        "balance": "0.01",
                        "available": "0.01",
                        "holds": "0",
                        "baseCurrency": "BTC",
                        "baseCurrencyPrice": "62514.5",
                        "baseAmount": "0.00000015",
                        "tag": "DEFAULT"
                    }
                ],
                "marginAccounts": [
                    {
                        "currency": "USDT",
                        "balance": "0.01",
                        "available": "0.01",
                        "holds": "0",
                        "baseCurrency": "BTC",
                        "baseCurrencyPrice": "62514.5",
                        "baseAmount": "0.00000015",
                        "tag": "DEFAULT"
                    }
                ],
                "tradeHFAccounts": []
            },
            {
                "subUserId": "670538a31037eb000115b076",
                "subName": "Name1234567",
                "mainAccounts": [],
                "tradeAccounts": [],
                "marginAccounts": [],
                "tradeHFAccounts": []
            },
            {
                "subUserId": "66b0c0905fc1480001c14c36",
                "subName": "LTkucoin1491",
                "mainAccounts": [],
                "tradeAccounts": [],
                "marginAccounts": [],
                "tradeHFAccounts": []
            }
        ]
    }
}

• The function handles pagination automatically, fetching all pages up to max_pages.

• Balance fields are converted from character to numeric types.

• Sub-accounts with no balance entries are not included in the resulting data.table.

Examples

if (FALSE) { # \dontrun{
keys <- get_api_keys()
base_url <- "https://api.kucoin.com"
main_async <- coro::async(function() {
  dt <- await(get_spot_subaccount_list_v2_impl(
    keys = keys,
    base_url = base_url,
    page_size = 50,
    max_pages = 2
  ))
  print(dt)
})
main_async()
while (!later::loop_empty()) later::run_now()
} # }