> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-Accounts Quickstart

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

Base URL

:

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](https://whitebit.com/auth/register))
* An API key with **Trade** permission and sub-account management capability ([create key](https://whitebit.com/settings/api))
* Funds in [Main balance](/concepts/balances) (sub-account transfers draw from Main balance)
* HMAC-SHA512 signing configured ([authentication guide](/api-reference/authentication))
* `curl` and `jq` installed (for command-line examples)

**1. Create a sub-account**

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

**cURL**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
  }'
```

**Python**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/sdks).

**Required fields:** `alias` (display name), `permissions` (object with `spotEnabled` and `collateralEnabled`). When `shareKyc` is `false` or omitted, `email` is also required.

**Expected response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

**2. Transfer funds to the sub-account**

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

**cURL**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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).

> [!WARNING]
>
> Save the `secretKey` immediately -- the API does not return the secret key again after creation.

> [!NOTE]
>
> 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](mailto:institutional@whitebit.com). Once enabled, generate the address via the
> standard [deposit-address endpoint](/api-reference/account-wallet/get-cryptocurrency-deposit-address)
> signed with the sub-account's own key.

**4. Check sub-account balances**

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

**cURL**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Sub as Sub-account (own key)
    participant WB as WhiteBIT
    participant Main as Main account (own key)
    Main->>WB: POST /sub-account/api-key/edit (enable withdraw URL)
    WB-->>Main: 200 — withdraw enabled on the key
    Sub->>WB: POST /main-account/withdraw
    WB-->>Sub: status unconfirmed_by_main_account
    Main->>WB: POST /sub-account/withdraw/unconfirmed-list
    WB-->>Main: pending withdrawals (transaction id)
    Main->>WB: POST /sub-account/withdraw/confirm (transaction id)
    WB-->>Main: 200 — released for processing
    Note over WB: Unconfirmed withdrawals expire if not confirmed
```

> [!NOTE]
>
> The sub-account withdrawal endpoints are not available by default. To request access, contact
> [institutional@whitebit.com](mailto:institutional@whitebit.com). Without main account confirmation, an unconfirmed withdrawal
> expires after a retention period.

**1. 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](/api-reference/sub-accounts/edit-sub-account-api-key)
(`POST /api/v4/sub-account/api-key/edit`):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/sub-accounts/list-sub-account-api-keys):
the withdraw URLs under `accessEndpoints` now show `enable: true`.

**2. 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](/api-reference/account-wallet/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.

**3. 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**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
  }'
```

**Python**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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`.

**4. 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**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
  }'
```

**Python**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/products/sub-accounts/overview)**
>
> Integration patterns for fund managers, account operators, and prop trading firms.

> **[Sub-account integration](/guides/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](/sdks).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.