> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sub-Accounts Quickstart
> Create a sub-account, transfer funds, generate an API key, and check balances -- step by step.
Each sub-account holds its own balance and API keys. Funds and signing scopes are isolated from the main account; transfers between them 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](https://whitebit.com/auth/register))
* An API key with **Trade** permission and sub-account management capability ([create key](https://whitebit.com/settings/api))
* Funds in [Main balance](/concepts/balances) (sub-account transfers draw from Main balance)
* HMAC-SHA512 signing configured ([authentication guide](/api-reference/authentication))
* `curl` and `jq` installed (for command-line examples)
Create a new sub-account with an alias and permissions.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://whitebit.com/api/v4/sub-account/create \
-H "Content-Type: application/json" \
-H "X-TXC-APIKEY: YOUR_API_KEY" \
-H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
-H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
-d '{
"alias": "strategy-alpha",
"email": "strategy-alpha@example.com",
"permissions": {"spotEnabled": true, "collateralEnabled": false},
"request": "/api/v4/sub-account/create",
"nonce": 1709340000000
}'
```
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests, json, hmac, hashlib, base64, time
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_SECRET"
BASE_URL = "https://whitebit.com"
def make_request(endpoint, body):
nonce = int(time.time() * 1000)
body["request"] = endpoint
body["nonce"] = nonce
data_json = json.dumps(body)
payload = base64.b64encode(data_json.encode())
signature = hmac.new(
API_SECRET.encode(), payload, hashlib.sha512
).hexdigest()
headers = {
"Content-Type": "application/json",
"X-TXC-APIKEY": API_KEY,
"X-TXC-PAYLOAD": payload.decode(),
"X-TXC-SIGNATURE": signature,
}
return requests.post(f"{BASE_URL}{endpoint}", headers=headers, data=data_json)
# Create a sub-account
response = make_request("/api/v4/sub-account/create", {
"alias": "strategy-alpha",
"email": "strategy-alpha@example.com",
"permissions": {"spotEnabled": True, "collateralEnabled": False},
})
sub_account = response.json()
print(json.dumps(sub_account, indent=2))
```
For Go and PHP examples, see [SDKs](/sdks).
**Required fields:** `alias` (display name), `permissions` (object with `spotEnabled` and `collateralEnabled`). When `shareKyc` is `false` or omitted, `email` is also required.
**Expected response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
"alias": "strategy-alpha",
"userId": "u-12345",
"email": "s***@example.com",
"status": "active",
"color": "#FF5733",
"kyc": {
"shareKyc": false,
"kycStatus": "verified"
},
"permissions": {
"spotEnabled": true,
"collateralEnabled": false
}
}
```
Save the `id` value for subsequent steps.
Move assets from the main account to the newly created sub-account.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://whitebit.com/api/v4/sub-account/transfer \
-H "Content-Type: application/json" \
-H "X-TXC-APIKEY: YOUR_API_KEY" \
-H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
-H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
-d '{
"id": "",
"direction": "main_to_sub",
"ticker": "USDT",
"amount": "100",
"request": "/api/v4/sub-account/transfer",
"nonce": 1709340000001
}'
```
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Transfer funds to sub-account
response = make_request("/api/v4/sub-account/transfer", {
"id": "",
"direction": "main_to_sub",
"ticker": "USDT",
"amount": "100",
})
print(response.json())
```
**Required fields:** `id` (sub-account UUID), `direction` (`main_to_sub` or `sub_to_main`), `ticker`, `amount`. Transfers are instant and fee-free.
**Expected response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"transaction_id": "tx_..."
}
```
Generate a dedicated API key for the sub-account to enable independent trading.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://whitebit.com/api/v4/sub-account/api-key/create \
-H "Content-Type: application/json" \
-H "X-TXC-APIKEY: YOUR_API_KEY" \
-H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
-H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
-d '{
"subAccountId": "",
"type": 1,
"title": "Trading Bot Key",
"request": "/api/v4/sub-account/api-key/create",
"nonce": 1709340000002
}'
```
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Create API key for sub-account
response = make_request("/api/v4/sub-account/api-key/create", {
"subAccountId": "",
"type": 1,
"title": "Trading Bot Key",
})
print(response.json())
```
**Required fields:** `subAccountId` (UUID), `type` (1 = info and trading, 2 = info, trading, deposits, withdrawals). **Optional:** `title` (custom name for the key).
Save the `secretKey` immediately -- the API does not return the secret key again after creation.
Verify that the transferred funds appear in the sub-account balance.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://whitebit.com/api/v4/sub-account/balances \
-H "Content-Type: application/json" \
-H "X-TXC-APIKEY: YOUR_API_KEY" \
-H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
-H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
-d '{
"id": "",
"request": "/api/v4/sub-account/balances",
"nonce": 1709340000003
}'
```
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Check sub-account balances
response = make_request("/api/v4/sub-account/balances", {
"id": "",
})
print(json.dumps(response.json(), indent=2))
```
**Expected response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"USDT": [
{
"main": "100",
"spot": "0",
"collateral": "0"
}
]
}
```
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.
## What's Next
Integration patterns for fund managers, brokers, and prop trading firms.
Fee share model up to 50%, sub-account-per-customer onboarding, KYC URL generation, and per-customer API keys with up to 50 IP addresses.
For Go and PHP examples, see [SDKs](/sdks).