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)
curlandjqinstalled (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: Save the
- cURL
- Python
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: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:
- cURL
- Python
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:
- cURL
- Python
subAccountId (UUID), type (1 = info and trading, 2 = info, trading, deposits, withdrawals), title (key name).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.
- cURL
- Python
main, spot, and collateral show available funds in each balance type for the sub-account.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
Each item includes the transaction
id of each transaction to confirm.- cURL
- Python
id, subAccountId, currency, amount, and createdAt.4
Confirm the withdrawal from the main account
Approve a listed withdrawal by external Confirmation is the only main-account action on an unconfirmed withdrawal — no reject endpoint
exists, and an unconfirmed withdrawal does not expire.
id. A successful call returns an empty object and
releases the withdrawal for processing.- cURL
- Python
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.