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 = 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 them for the account and its sub-accounts, contact your 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.

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, 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 TypeScript and Python SDK examples, see SDKs.

​Prerequisites

​Sub-account withdrawal approval

​What’s Next

Sub-Accounts Overview

Broker Guide

Prerequisites

Sub-account withdrawal approval

What’s Next