Sub-Accounts Quickstart

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)

Create a sub-account

Create a new sub-account with an alias and permissions.

cURL
Python

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
  }'

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 TypeScript and Python SDK examples, see SDKs.Required fields: alias (display name), permissions (object with spotEnabled and collateralEnabled). When shareKyc is false or omitted, email is also required.Expected response:

{
  "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.

Transfer funds to the sub-account

Move assets from the main account to the newly created sub-account.

cURL
Python

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": "<sub-account-id-from-step-1>",
    "direction": "main_to_sub",
    "ticker": "USDT",
    "amount": "100",
    "request": "/api/v4/sub-account/transfer",
    "nonce": 1709340000001
  }'

# Transfer funds to sub-account
response = make_request("/api/v4/sub-account/transfer", {
    "id": "<sub-account-id-from-step-1>",
    "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:

{
  "transaction_id": "tx_..."
}

Create an API key for the sub-account

Generate a dedicated API key for the sub-account to enable independent trading.

cURL
Python

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": "<sub-account-id-from-step-1>",
    "type": 1,
    "title": "Trading Bot Key",
    "request": "/api/v4/sub-account/api-key/create",
    "nonce": 1709340000002
  }'

# Create API key for sub-account
response = make_request("/api/v4/sub-account/api-key/create", {
    "subAccountId": "<sub-account-id-from-step-1>",
    "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.

To receive crypto deposits directly, the sub-account needs a type: 2 key (deposits and withdrawals) and the account must have deposits enabled. Crypto deposits are disabled by default — to enable crypto deposits for the account and its sub-accounts, contact the assigned Account Manager or email institutional@whitebit.com. Once enabled, generate the address via the standard deposit-address endpoint signed with the sub-account’s own key.

Check sub-account balances

Verify that the transferred funds appear in the sub-account balance.

cURL
Python

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": "<sub-account-id-from-step-1>",
    "request": "/api/v4/sub-account/balances",
    "nonce": 1709340000003
  }'

# Check sub-account balances
response = make_request("/api/v4/sub-account/balances", {
    "id": "<sub-account-id-from-step-1>",
})
print(json.dumps(response.json(), indent=2))

Expected response:

{
  "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.

Sub-account withdrawal approval

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.

The sub-account withdrawal endpoints are not available by default. To request access, contact institutional@whitebit.com. Without main account confirmation, an unconfirmed withdrawal expires after a retention period.

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. 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."}. Enable it from the main account with Edit Sub-Account API Key (POST /api/v4/sub-account/api-key/edit):

curl -X POST https://whitebit.com/api/v4/sub-account/api-key/edit \
  -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 '{
    "apiKeyId": "SUB_ACCOUNT_API_KEY_ID",
    "title": "Trading Bot Key",
    "urls": [
      { "url": "/api/v4/main-account/withdraw", "enable": true }
    ],
    "request": "/api/v4/sub-account/api-key/edit",
    "nonce": 1709340000006
  }'

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.

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.

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.

cURL
Python

curl -X POST https://whitebit.com/api/v4/sub-account/withdraw/unconfirmed-list \
  -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 '{
    "limit": 100,
    "offset": 0,
    "request": "/api/v4/sub-account/withdraw/unconfirmed-list",
    "nonce": 1709340000004
  }'

# List unconfirmed sub-account withdrawals
response = make_request("/api/v4/sub-account/withdraw/unconfirmed-list", {
    "limit": 100,
    "offset": 0,
})
print(json.dumps(response.json(), indent=2))

Each item includes the transaction id, subAccountId, currency, amount, and createdAt.

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.

cURL
Python

curl -X POST https://whitebit.com/api/v4/sub-account/withdraw/confirm \
  -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": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "request": "/api/v4/sub-account/withdraw/confirm",
    "nonce": 1709340000005
  }'

# Confirm a sub-account withdrawal
response = make_request("/api/v4/sub-account/withdraw/confirm", {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
})
print(response.status_code, response.json())

Confirmation is the only main-account action on an unconfirmed withdrawal — no reject endpoint exists, and an unconfirmed withdrawal that is never confirmed expires automatically.

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.

​Prerequisites

​Sub-account withdrawal approval

​What’s Next

Sub-Accounts Overview

Sub-account integration

Prerequisites

Sub-account withdrawal approval

What’s Next