Sub-Accounts Quickstart

Create a sub-account, transfer funds, generate an API key, and check balances — step by step.

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)

1. Create a sub-account

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

   cURL

   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": "[e-mail]",
       "permissions": {"spotEnabled": true, "collateralEnabled": false},
       "request": "/api/v4/sub-account/create",
       "nonce": "1709340000000"
     }'
   

   Python

   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": "[e-mail]",
       "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.

2. Transfer funds to the sub-account

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

   cURL

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

   Python

   # 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_..."
   }
   
3. Create an API key for the sub-account

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

   cURL

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

   Python

   # 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.

4. Check sub-account balances

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

   cURL

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

   Python

   # 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.