Sub-Accounts Quickstart

Create a sub-account, transfer funds into the sub-account, generate a dedicated API key, and verify the balance — all via API.

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: An object containing the sub-account id. Save the id 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: A balance object showing the transferred USDT funds.

The sub-account now has an independent balance and API key. The API key can be used independently for trading operations on the sub-account. To manage IP whitelists for the new key, use POST /api/v4/sub-account/api-key/ip-address/create.

What’s Next

Sub-Accounts Overview

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

Broker Guide

End-to-end integration guide for the Broker Program.

For Go and PHP examples, see SDKs.

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

Sub-Accounts Quickstart

Prerequisites

What’s Next

Sub-Accounts Overview

Broker Guide

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

​Prerequisites

​What’s Next

Sub-Accounts Overview

Broker Guide

Prerequisites

What’s Next