Skip to main content
Each sub-account holds its own balance and API keys. Funds and signing scopes are isolated from the main account; transfers between the two accounts are explicit and fee-free. The four steps below set up that isolation, from creation through balance verification.

Prerequisites

  • A WhiteBIT account with completed KYC (register)
  • An API key with Trade permission and sub-account management capability (create key)
  • Funds in Main balance (sub-account transfers draw from Main balance)
  • HMAC-SHA512 signing configured (authentication guide)
  • curl and jq installed (for command-line examples)
1

Create a sub-account

Create a sub-account that shares the main account’s verification, with an alias and permissions.
For TypeScript and Python SDK examples, see SDKs.Required fields: alias (display name, unique among the main account’s sub-accounts), permissions (object with spotEnabled and collateralEnabled). When shareKyc is false or omitted, email is also required. The example sets shareKyc: true and leaves email out, so the sub-account shares the main account’s verification and is active at creation.A request with email starts the invitation flow instead: WhiteBIT emails the end customer, and the sub-account stays inactive until the customer opens the link and sets a password. Until then, transfers and balances for the sub-account are refused. The invitation link expires after three days and can be re-sent on whitebit.com, not through the API. Once List of Sub-Accounts shows the sub-account’s status as active, set depositsEnabled and withdrawsEnabled with Edit Sub-Account, sending the alias and the full permissions object (spotEnabled and collateralEnabled as set at creation), then create the sub-account’s API key. Transfers from the main account to a sub-account created with shareKyc: false also wait for the end customer’s KYC approval. See the customer onboarding flow.Expected response:
Save the id value for subsequent steps.
2

Transfer funds to the sub-account

Move assets from the main account to the newly created sub-account.
Required fields: id (sub-account UUID), direction (main_to_sub or sub_to_main), ticker, amount. Transfers are fee-free. The response means WhiteBIT accepted the request, and the transfer can still fail after it. Confirm the transfer on the sub-account’s main balance with POST /api/v4/sub-account/balances, as in the Check sub-account balances step below, before acting on it.Expected response:
3

Create an API key for the sub-account

Generate a dedicated API key for the sub-account to enable independent trading.
Required fields: subAccountId (UUID), type (1 = info and trading, 2 = info, trading, deposits, withdrawals), title (key name).
Save the secretKey immediately — the API does not return the secret key again after creation.
To receive crypto deposits directly, the sub-account needs a type: 2 key (deposits and withdrawals) and the account must have sub-account deposits enabled. Crypto deposits to sub-accounts are disabled by default — to enable deposits for the account’s sub-accounts, contact the assigned account manager. Once deposits are enabled, use Edit Sub-Account API Key to enable /api/v4/main-account/address on the type: 2 key (every URL group starts switched off on a new key), then generate the address via the standard deposit-address endpoint signed with the sub-account’s own key. The sub-account also needs its own deposit permission, depositsEnabled: in the create request for a sub-account created without email, otherwise with Edit Sub-Account once the sub-account is active.
4

Check sub-account balances

Verify that the transferred funds appear in the sub-account balance.
Expected response:
The response keys ticker symbols to an array of balance objects. main, spot, and collateral show available funds in each balance type for the sub-account.
The sub-account now has an isolated balance and a dedicated API key. To restrict the key to known IPs, call POST /api/v4/sub-account/api-key/ip-address/create with the whitelist.

Sub-account withdrawal approval

A sub-account withdrawal needs the sub-account’s own withdrawal permission, withdrawsEnabled: set in the create request for a sub-account created without email, otherwise with Edit Sub-Account once the sub-account is active. When the sub-account withdrawal feature is enabled, a withdrawal created with a sub-account key does not settle immediately. The transaction enters unconfirmed_by_main_account status and waits for main account approval, giving the main account a control point over every sub-account withdrawal. No webhook is sent while the withdrawal waits. After confirmation, the withdrawal follows the standard path: the first webhook event is withdraw.unconfirmed (status 5), then withdraw.pending and a final event. These events go to the webhook of the sub-account that owns the withdrawal, not to the main account’s webhook.
The sub-account withdrawal endpoints are not available by default. To request access, contact the assigned account manager. An unconfirmed withdrawal does not expire.
1

Enable the withdrawal endpoint on the sub-account key

A newly created type: 2 key lists the withdraw and deposit groups in accessEndpoints, but each URL defaults to enable: false, as in every other URL group on a new key. Until the withdraw URL is enabled, POST /api/v4/main-account/withdraw returns 401 with {"code":4,"message":"This API Key is not authorized to perform this action."}. Only a type: 2 key accepts the withdraw URL: on a type: 1 key, such as the trading key created earlier in this guide, the edit returns 400 with code 5 (The following URLs are restricted for sub-account API keys). If the sub-account has no type: 2 key yet, create one with Create Sub-Account API Key as in the API key step above, with "type": 2. Enable the withdraw URL from the main account with Edit Sub-Account API Key (POST /api/v4/sub-account/api-key/edit):
title is required; reuse the key’s current title to avoid renaming it. The urls array is merged into the key’s existing settings, so enabling the withdraw URLs leaves other endpoints untouched. Verify with List Sub-Account API Keys: the withdraw URLs under accessEndpoints now show enable: true.
2

Initiate the withdrawal from the sub-account

The sub-account creates the withdrawal with the sub-account’s own type: 2 API key (deposits and withdrawals) on the standard Create withdraw request endpoint (POST /api/v4/main-account/withdraw). No main-account-side initiation endpoint exists — the request is signed with the sub-account key. The resulting transaction enters unconfirmed_by_main_account status.
3

List pending withdrawals from the main account

Using a main-account key, list the sub-account withdrawals awaiting approval. Capture the id of each transaction to confirm.
Each item includes the transaction id, subAccountId, currency, amount, and createdAt.
4

Confirm the withdrawal from the main account

Approve a listed withdrawal by external id. A successful call returns an empty object and releases the withdrawal for processing.
Confirmation is the only main-account action on an unconfirmed withdrawal — no reject endpoint exists, and an unconfirmed withdrawal does not expire.

What’s Next

Sub-Accounts Overview

Integration patterns for fund managers, account operators, and prop trading firms.

Sub-account integration

Fee share up to 40%, sub-account-per-customer onboarding, KYC URL generation, and per-customer API keys with dedicated IP whitelists.
For TypeScript and Python SDK examples, see SDKs.