Broker Integration Guide

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.

​

Broker Program overview

Referred user trades $10,000 on BTC_USDT (spot)
Standard trading fee: 0.1% taker = $10.00
Broker fee share (40%): $10.00 × 0.40 = $4.00

• Per-customer sub-accounts: each end customer trades from a dedicated sub-account with its own balance, order history, and API credentials
• Per-customer API keys
• Fee-free internal transfers between master and sub-accounts
• Joint marketing activities: social media co-posts, blog posts, targeted email newsletters, AMA sessions, and trading competitions, scheduled with WhiteBIT during onboarding

​

Customer onboarding flow

# Create a sub-account
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": "customer-001",
    "request": "/api/v4/sub-account/create",
    "nonce": "YOUR_NONCE"
  }'

# Generate a KYC URL for the sub-account
curl -X POST "https://whitebit.com/api/v4/sub-account/kyc-url" \
  -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",
    "request": "/api/v4/sub-account/kyc-url",
    "nonce": "YOUR_NONCE"
  }'

import hashlib
import hmac
import json
import time
import base64
import requests

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_SECRET"
BASE_URL = "https://whitebit.com"

def send_request(endpoint, payload):
    payload["request"] = endpoint
    payload["nonce"] = str(int(time.time() * 1000))
    body = json.dumps(payload)
    encoded = base64.b64encode(body.encode()).decode()
    signature = hmac.new(
        API_SECRET.encode(), encoded.encode(), hashlib.sha512
    ).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "X-TXC-APIKEY": API_KEY,
        "X-TXC-PAYLOAD": encoded,
        "X-TXC-SIGNATURE": signature,
    }
    return requests.post(f"{BASE_URL}{endpoint}", headers=headers, data=body)

# Create a sub-account
response = send_request("/api/v4/sub-account/create", {
    "alias": "customer-001",
})
sub_account = response.json()
print(sub_account)

# Generate a KYC URL
response = send_request("/api/v4/sub-account/kyc-url", {
    "id": sub_account.get("id"),
})
print(response.json())

​

Sub-account management

• Master to sub-account: funding a customer account
• Sub-account to master: revenue collection

​

Per-customer API keys

• Create API keys per sub-account for customers who need direct API access
• IP whitelisting: up to 50 IP addresses per API key
• Permissions: configure per-key permissions (Info + Trading vs. Info + Trading + Deposit + Withdraw)

​

Revenue monitoring

1. List sub-accounts via POST /api/v4/sub-account/list.
2. For each sub-account, query trade history via POST /api/v4/trade-account/executed-history using the sub-account’s own API key — see the API Reference.
3. For each executed deal, multiply the fee charged by the broker’s active fee-share percentage from the WBT tier table.
4. Sum across all sub-accounts to produce the broker’s earnings for the reporting window.

• Reconcile against the dashboard monthly so dashboard-credited payouts match locally computed totals.
• Track each referred user’s trading volume separately — a single high-volume customer can change the master account’s effective fee tier and lift the absolute fee share without any new customers being added.
• Export per-sub-account trade history into a ledger column matching the monthly settlement statement.

​

Fiat for broker end users

​

Integration checklist

• Program enrollment — Application submitted to institutional@whitebit.com and approved.
• Master account KYB — KYB verification completed for the broker entity.
• API key generated — Master account API key created with appropriate permissions.
• Sub-account creation — Successfully created at least one test sub-account.
• KYC URL generation — KYC URL generated and tested for a sub-account.
• Fund transfer — Fee-free transfer between master and sub-account verified.
• Per-customer API key — API key created for a sub-account with IP whitelist configured.
• Balance monitoring — Sub-account balance query working.
• Fee share tracking — Revenue monitoring process established.
• Fiat access (if applicable) — Institutional onboarding Phase 2 completed for SEPA access.
• Security review — IP whitelists, API key permissions, and secret storage reviewed per Security Best Practices.
• Go-live review — All items on the Go-Live Checklist verified.

​

What’s Next