Retrieve Sub-Account Balance Details (Implementation)

Retrieves balance details for a specific sub-account from KuCoin asynchronously, aggregating account types 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_detail_balance_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  subUserId,
  includeBaseAmount = FALSE,
  .__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().

subUserId

Character string representing the sub-account user ID for which balance details are retrieved.

includeBaseAmount

Logical flag indicating whether to include currencies with a zero balance in the response. Defaults to FALSE.

Value

Promise resolving to a data.table containing detailed balance information for the specified sub-account, with columns including:

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

• subName (character): Sub-account name.

• 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.

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

Details

Workflow Overview

1. URL and Query String Construction: Constructs the endpoint URL by appending subUserId to /api/v1/sub-accounts/ and adding the includeBaseAmount query parameter (defaulting to FALSE).

2. Header Generation: Generates authentication headers asynchronously via build_headers().

3. HTTP Request: Sends a GET request to the constructed URL with a 3-second timeout using httr::GET().

4. Response Processing: Parses the JSON response with process_kucoin_response(), converting each non-empty account type array (mainAccounts, tradeAccounts, marginAccounts, tradeHFAccounts) into a data.table with an added accountType column.

5. Aggregation and Metadata Addition: Aggregates all non-empty data.tables into a single data.table using data.table::rbindlist(), appending subUserId and subName to each row.

API Endpoint

GET https://api.kucoin.com/api/v1/sub-accounts/{subUserId}?includeBaseAmount={includeBaseAmount}

Usage

Utilised internally to provide detailed balance information across various account categories for a specified sub-account.

Official Documentation

KuCoin Get Sub-Account Detail Balance

Raw Response Schema:

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

• data (object): Contains subUserId, subName, and arrays for mainAccounts, tradeAccounts, marginAccounts, and tradeHFAccounts.

KuCoin's API docs list this as the return data schema:

{
    "code": "200000",
    "data": {
        "subUserId": "63743f07e0c5230001761d08",
        "subName": "testapi6",
        "mainAccounts": [
            {
                "currency": "USDT",
                "balance": "0.01",
                "available": "0.01",
                "holds": "0",
                "baseCurrency": "BTC",
                "baseCurrencyPrice": "62384.3",
                "baseAmount": "0.00000016",
                "tag": "DEFAULT"
            }
        ],
        "tradeAccounts": [
            {
                "currency": "USDT",
                "balance": "0.01",
                "available": "0.01",
                "holds": "0",
                "baseCurrency": "BTC",
                "baseCurrencyPrice": "62384.3",
                "baseAmount": "0.00000016",
                "tag": "DEFAULT"
            }
        ],
        "marginAccounts": [
            {
                "currency": "USDT",
                "balance": "0.01",
                "available": "0.01",
                "holds": "0",
                "baseCurrency": "BTC",
                "baseCurrencyPrice": "62384.3",
                "baseAmount": "0.00000016",
                "tag": "DEFAULT"
            }
        ],
        "tradeHFAccounts": []
    }
}

Examples

if (FALSE) { # \dontrun{
keys <- get_api_keys()
base_url <- "https://api.kucoin.com"
subUserId <- "63743f07e0c5230001761d08"
main_async <- coro::async(function() {
  dt <- await(get_subaccount_detail_balance_impl(
    keys = keys,
    base_url = base_url,
    subUserId = subUserId,
    includeBaseAmount = TRUE
  ))
  print(dt)
})
main_async()
while (!later::loop_empty()) later::run_now()
} # }