Embedded Trading Integration Guide

• End customers keep personal WhiteBIT accounts and the partner holds a user-scoped API key (trading bots, copy trading, portfolio apps) — see Fast API Key via OAuth.
• The choice between backend models (managed sub-accounts, attribution, KYC reliance) is still open — see Wallet-as-a-Service.
• The integration centers on deposits, withdrawals, payouts, or merchant flows — see Payment Integration. Corporate fiat ↔ crypto conversion on the partner’s own account is covered by the On/Off-Ramp Guide.
• For the full partner-type map, see Partner Solutions.

​

Prerequisites

• Approved Embedded Trading enrollment — the program is approval-gated (see Eligibility and approval); apply via institutional@whitebit.com.
• Master-account KYB — completed through Institutional Onboarding.
• API access — HMAC-signed requests on the master account; store the secret per Security Best Practices.
• Model fit — this is Model A (partner-operated sub-accounts); confirm against the integration models concept.

​

Eligibility and approval

​

Program terms

​

Account architecture

• Independent balances, scoped at creation via permissions.spotEnabled and permissions.collateralEnabled. Trades on one sub-account do not affect another.
• Up to 50 API keys per sub-account, independent from the main account and from other sub-accounts, each with an IP whitelist and permission scope.
• Sub-account count per master — the number of sub-accounts a master account can create is not a fixed published limit; confirm the ceiling that applies to the account with WhiteBIT during enrollment.

• Withdrawal control at the master account — sub-account withdrawals surface on the master account for confirmation via the unconfirmed-withdrawals list and confirm endpoints. The sub-account withdrawal endpoints are not available by default — request access via institutional@whitebit.com; a 404 response indicates the endpoints are not yet enabled for the account.
• Crypto deposits are disabled by default. Once deposits are enabled for the account (request via the assigned account manager or institutional@whitebit.com), the capability applies to the account and its sub-accounts; a sub-account then generates deposit addresses through the standard deposit address endpoint using its own API key with deposit permission.

​

Customer onboarding flow

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",
    "email": "customer@example.com",
    "shareKyc": false,
    "permissions": {"spotEnabled": true, "collateralEnabled": false},
    "request": "/api/v4/sub-account/create",
    "nonce": 1594297865000
  }'

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

API_KEY, API_SECRET = "YOUR_API_KEY", "YOUR_SECRET"
endpoint = "/api/v4/sub-account/create"
body = json.dumps({
    "alias": "customer-001",
    "email": "customer@example.com",
    "shareKyc": False,
    "permissions": {"spotEnabled": True, "collateralEnabled": False},
    "request": endpoint,
    "nonce": int(time.time() * 1000),
})
payload = base64.b64encode(body.encode()).decode()
signature = hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha512).hexdigest()
response = requests.post(
    "https://whitebit.com" + endpoint,
    headers={"Content-Type": "application/json", "X-TXC-APIKEY": API_KEY,
             "X-TXC-PAYLOAD": payload, "X-TXC-SIGNATURE": signature},
    data=body,
)
print(response.json())  # id, alias, userId, email, status

​

Per-customer API keys

• Assign the minimum permission set per key (Info + Trading for trading-only customers; deposit and withdrawal permissions only where funds movement is required) — see Security Best Practices for the permission model and key-handling rules.
• Configure the IP whitelist per key to match the customer’s infrastructure.

​

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 — API Reference.
3. For each executed deal, multiply the fee charged by the agreed fee-share percentage.
4. Sum across all sub-accounts to produce earnings for the reporting window.

​

Fiat operations

​

Testing

​

Integration checklist

• Application — application sent to institutional@whitebit.com with the intake details and approved.
• Master account KYB — KYB verification completed for the partner entity.
• Master API key — master account API key created with appropriate permissions.
• Sub-account creation — test sub-account created with the intended permissions scope and KYC branch.
• Activation and KYC — sub-account activation observed via sub-account/list; KYC URL generated and completed (dedicated-KYC branch).
• Deposit enablement (if per-customer deposits apply) — crypto-deposit enablement requested via the account manager or institutional@whitebit.com.
• Fund transfer — fee-free transfer between master and sub-account verified in both directions.
• Per-customer API key — API key created for a sub-account with IP whitelist configured.
• Balance monitoring — sub-account/balances query working across all sub-accounts.
• Revenue reconciliation — per-sub-account trade-history collection and fee-share computation in place.
• Fiat access (if applicable) — institutional onboarding Phase 2 completed for SEPA access on the master account.
• Security review — IP whitelists, key permissions, and secret storage reviewed per Security Best Practices.
• Go-live review — all items on the Go-Live Checklist verified.

​

What’s next