Bybit Sub-Accounts Tutorial: Best Setup for Crypto Trading Bots

At its core, a Bybit Sub-Account functions as an independent trading entity nested under a Master (or Main) Account. While the Master Account retains ultimate control over asset clearings, deposits, withdrawals, and structural security permissions, each sub-account operates with its own distinct balance sheet, trading history, open positions, and, most importantly, dedicated API endpoints.

For automated trading frameworks, this nesting structure provides several fundamental advantages:

1. Hard Risk Isolation and Margin Segmentation

When running multiple automated trading bots, a catastrophic market event or a software bug in an experimental script can trigger unexpected margin calls. If these strategies run inside the same account, a single failing position can drain the collateral required by other completely unrelated, highly profitable strategies. By isolating each trading bot into its own dedicated sub-account, you establish an iron-clad firewall. If a high-risk grid bot running in Sub-Account A experiences an unprecedented adverse price excursion, its liquidation risk is strictly capped at the collateral allocated to Sub-Account A. The capital powering a conservative trend-following strategy in Sub-Account B remains entirely untouched.

2. Multiplied API Rate Limits and Endpoint Optimization

Bybit enforces strict rate limits on API requests (REST requests per second and WebSocket connection limits) to maintain exchange stability. High-frequency trading (HFT) bots or multi-pair market makers can easily exhaust standard API rate limits, resulting in HTTP 429 Too Many Requests errors, missed executions, or disconnected data streams. Bybit calculates API rate limits per account. By distributing five distinct trading bots across five separate sub-accounts, you effectively scale your available API throughput, circumventing standard rate-limiting bottlenecks without requiring specialized institutional tier upgrades.

3. Strategy Performance Attribution and Granular Analytics

Accurately calculating the Sharpe ratio, maximum drawdown, and net return on investment (ROI) for individual trading algorithms becomes incredibly complex when trades are mixed in a single order book. Sub-accounts offer absolute data isolation. Every ledger entry, filled order, funding fee payment, and PnL calculation is tracked independently per sub-account. This allows developers to hook up clean data pipelines to custom dashboards or analytical engines, evaluating each algorithm's performance in absolute isolation.

When provisioning a new sub-account on Bybit, traders must choose the account type structure. The modern standard on Bybit is the Unified Trading Account (UTA), a highly advanced account structure that significantly alters how collateral, margin, and multi-asset trading operate. For algorithmic developers, understanding how the UTA functions inside sub-accounts is vital.

Why Every Trading Bot Sub-Account Should Use UTA

The Unified Trading Account system is purpose-built for programmatic execution. Under a sub-account configured for UTA, your bot can use its entire asset portfolio as collateral. For instance, if your bot holds Spot Bitcoin (BTC) inside the sub-account, it can immediately open a short position on ETHUSDT perpetual contracts without needing to manually swap BTC into USDT first. Bybit automatically calculates the total USD-equivalent value of the sub-account's assets (applying specific asset valuation "haircuts" to account for volatility) to determine the maintenance and initial margin.

This prevents capital fragmentation. Instead of leaving idle USDT in a derivatives wallet and idle BTC in a spot wallet, the UTA merges these balances, dramatically lowering the overall margin liquidation threshold and maximizing capital efficiency.

Bybit allows the creation and management of sub-accounts via both the web graphical user interface (GUI) and programmatically through the Master Account API endpoints.

Method A: Manual Configuration via the Bybit Dashboard

Method B: Programmatic Sub-Account Provisioning via API

For large-scale systematic operations, managing dozens of sub-accounts via the GUI is inefficient. Bybit exposes Master Account endpoints to automate sub-account provisioning. Using Python and the official pybit SDK or direct requests, developers can spin up sub-accounts on-demand.

Below is an institutional-grade Python script illustrating how to programmatically create a new sub-account, upgrade it to a Unified Trading Account, and generate custom API keys for a trading bot.

import time
import hmac
import hashlib
import requests
import json

class BybitMasterClient:
    def __init__(self, api_key, api_secret, base_url="https://api.bybit.com"):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = base_url

    def _generate_signature(self, timestamp, payload):
        param_str = str(timestamp) + self.api_key + "10000" + payload
        return hmac.new(
            self.api_secret.encode('utf-8'), 
            param_str.encode('utf-8'), 
            hashlib.sha256
        ).hexdigest()

    def send_request(self, method, endpoint, data=None):
        timestamp = int(time.time() * 1000)
        payload = json.dumps(data) if data else ""
        signature = self._generate_signature(timestamp, payload)
        
        headers = {
            "X-BAPI-API-KEY": self.api_key,
            "X-BAPI-SIGN": signature,
            "X-BAPI-TIMESTAMP": str(timestamp),
            "X-BAPI-RECV-WINDOW": "10000",
            "Content-Type": "application/json"
        }
        
        url = f"{self.base_url}{endpoint}"
        if method.upper() == "POST":
            response = requests.post(url, headers=headers, data=payload)
        else:
            response = requests.get(url, headers=headers)
        return response.json()

if __name__ == "__main__":
    # Initialize with your Master Account API credentials
    MASTER_KEY = "YOUR_MASTER_API_KEY"
    MASTER_SECRET = "YOUR_MASTER_API_SECRET"
    
    client = BybitMasterClient(MASTER_KEY, MASTER_SECRET)
    
    # 1. Create a new Sub-Account
    create_params = {
        "username": "AlgoBotSubAccountX1",
        "memberType": 1, # 1 denotes normal standard sub-account
        "note": "Dedicated sub-account for High-Frequency MACD Mean Reversion Strategy"
    }
    
    creation_response = client.send_request("POST", "/v5/user/create-sub-member", create_params)
    print("Creation Response:", json.dumps(creation_response, indent=2))
    
    if creation_response.get("retCode") == 0:
        sub_uid = creation_response["result"]["uid"]
        print(f"Successfully provisioned Sub-Account UID: {sub_uid}")
        
        # 2. Generate a dedicated API Key pair for this Sub-Account
        api_key_params = {
            "subuid": int(sub_uid),
            "readOnly": 0, # 0 means Read/Write permissions for executing orders
            "permissions": {
                "ContractTrade": ["Order", "Position"],
                "Spot": ["Trade"],
                "USDCContract": ["Order", "Position"],
                "AccountTransfer": ["SubMemberTransferList"]
            },
            "ips": ["45.12.34.11", "45.12.34.12"], # Whitelist your secure trading bot server IPs
            "note": "Bot Execution Key Pair"
        }
        
        api_response = client.send_request("POST", "/v5/user/create-subapi", api_key_params)
        print("Sub-Account API Keys Created:", json.dumps(api_response, indent=2))

When managing automated trading setups via sub-accounts, the rule of least privilege must be strictly implemented across all API structures. Because sub-accounts are sandboxed, a security failure on an isolated bot will not compromise your entire capital base—provided your permissions are configured correctly.

A common requirement for automated quantitative systems is dynamic asset reallocation. For example, if a trend-following bot in Sub-Account 1 generates substantial profits, a quantitative system may want to programmatically harvest those gains and reallocate them to a market-making bot in Sub-Account 2 that requires additional deep liquidity.

Bybit's API V5 allows seamless, zero-fee, instant asset transfers across the master-sub infrastructure via the Master Account API endpoints.

Python Routine for Master-Controlled Sub-Account Transfers

To execute a transfer, your master system needs to trigger the /v5/asset/transfer/universal-transfer endpoint.

def execute_internal_capital_reallocation(master_client, from_uid, to_uid, coin, amount):
    """
    Executes a zero-fee universal transfer between any sub-accounts controlled by the Master Account.
    """
    transfer_payload = {
        "transferId": f"tx-uuid-{int(time.time())}", # Must be a totally unique UUID string
        "coin": coin,
        "amount": str(amount),
        "fromMemberId": str(from_uid),
        "toMemberId": str(to_uid),
        "fromAccountType": "UNIFIED",
        "toAccountType": "UNIFIED"
    }
    
    response = master_client.send_request("POST", "/v5/asset/transfer/universal-transfer", transfer_payload)
    return response

By leveraging this endpoint, developers can build background scripts that automatically rebalance margin distributions based on real-time maximum drawdown metrics, ensuring optimal capital deployment across a diverse suite of automated trading frameworks.

One of the most profound mistakes systematic crypto traders make is running multiple heavy WebSocket connections or high-frequency REST polling instances inside a single account environment. This creates severe structural lag, increases order latency, and triggers exchange blocks.

The Mechanics of Bybit Rate Limits

Bybit structures REST API limits using a rolling window mechanism based on account identifiers. For instance, the default limit for order creation on Bybit V5 for a standard VIP 0 account might be 10 requests per second (RPS).

If a single script trades 15 different pairs simultaneously from one account, it will inevitably hit the 10 RPS ceiling during periods of high market volatility, leading to failed execution commands. By assigning those 15 pairs across 3 separate sub-accounts (5 pairs per sub-account), your aggregate operational limit scales to 30 RPS across the exact same capital base.

Advanced WebSocket Design Patterns for Sub-Accounts

To maximize execution velocity and minimize local resource consumption, adhere to the following architectural guidelines:

• Decouple Private and Public Streams: Never subscribe to public market data tickers (order books, trades, klines) and private account streams (position updates, order executions) using the exact same WebSocket connection. Public data streams are highly verbose and can saturate your local network thread, delaying the receipt of critical private execution fill confirmations.
• Local Order Book Ingestion: Use a dedicated, unified background service to pull public order books via a single Master connection, and broadcast that data internally to your bots via ultra-fast local protocols (e.g., Redis Pub/Sub, gRPC, ZeroMQ). Each individual sub-account bot should only connect directly to its own private WebSocket stream (/v5/private) to listen for its custom order fulfillment events.

Even experienced quantitative developers encounter operational challenges when interacting with sub-account network frameworks. Below is a checklist of critical failure modes and how to programmatically circumvent them.

To ensure your algorithmic execution structure is operating at peak industrial capability, cross-reference your current infrastructure layout against this rigorous performance checklist: