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 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)
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 = str(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.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.

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.

What’s Next

Sub-Accounts Overview

Integration patterns for fund managers, brokers, and prop trading firms.

Broker Guide

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.

Group

Documentation Index

​Prerequisites

​What’s Next

Sub-Accounts Overview

Broker Guide

Prerequisites

What’s Next