subAccounts | Hyperliquid info

​

Parameters

​

Request body

• type (string, required) — The request type. Must be "subAccounts" to retrieve sub-accounts associated with a user.
• user (string, required) — Address in 42-character hexadecimal format of the master account (e.g., 0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036).

​

Response

​

Sub-account identification

• subAccountUser (string) — Address of the sub-account in 42-character hexadecimal format
• name (string) — Human-readable name assigned to the sub-account for identification
• master (string) — Address of the master account (matches the requested user)

​

Perpetuals account state

• clearinghouseState (object) — Current perpetuals trading state of the sub-account:
  • marginSummary (object) — Overall margin information:
    • accountValue (string) — Total account value including unrealized profit and loss
    • totalNtlPos (string) — Total notional position value
    • totalRawUsd (string) — Total raw USD value in the account
    • totalMarginUsed (string) — Total margin currently allocated to open positions
  • crossMarginSummary (object) — Cross-margin specific information:
    • accountValue (string) — Account value for cross-margin calculations
    • totalNtlPos (string) — Total notional position value for cross-margin
    • totalRawUsd (string) — Total raw USD for cross-margin
    • totalMarginUsed (string) — Total margin used in cross-margin mode
  • crossMaintenanceMarginUsed (string) — Cross maintenance margin currently in use
  • withdrawable (string) — Amount available for withdrawal
  • assetPositions (array) — Array of current perpetuals positions (empty if no positions)
  • time (integer) — Timestamp of the state snapshot in milliseconds

​

Spot account state

• spotState (object) — Current spot trading state of the sub-account:
  • balances (array) — Array of spot token balances:
    • coin (string) — Token symbol (e.g., “USDC”)
    • token (integer) — Token index identifier
    • total (string) — Total balance including held amounts
    • hold (string) — Amount currently on hold (locked in orders)
    • entryNtl (string) — Entry notional value for cost basis tracking

​

Understanding sub-accounts

• Portfolio segregation: Separate trading strategies or asset classes
• Risk isolation: Limit exposure by isolating positions across accounts
• Strategy organization: Dedicated accounts for different trading approaches
• Performance tracking: Monitor results of specific strategies independently

• Master account: Primary account with overall control and access
• Sub-accounts: Secondary accounts managed under the master account
• Unified management: Master account can oversee all sub-account activities

• Multi-strategy trading: Different accounts for different trading strategies
• Risk management: Isolate high-risk trades from conservative positions
• Team management: Separate accounts for different team members or roles
• Asset segregation: Dedicated accounts for specific asset classes

​

Example request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "subAccounts", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036"}' \
  https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info

​

Example response

[
  {
    "name": "Test",
    "subAccountUser": "0x035605fc2f24d65300227189025e90a0d947f16c",
    "master": "0x8c967e73e6b15087c42a10d344cff4c96d877f1d",
    "clearinghouseState": {
      "marginSummary": {
        "accountValue": "29.78001",
        "totalNtlPos": "0.0",
        "totalRawUsd": "29.78001",
        "totalMarginUsed": "0.0"
      },
      "crossMarginSummary": {
        "accountValue": "29.78001",
        "totalNtlPos": "0.0",
        "totalRawUsd": "29.78001",
        "totalMarginUsed": "0.0"
      },
      "crossMaintenanceMarginUsed": "0.0",
      "withdrawable": "29.78001",
      "assetPositions": [],
      "time": 1733968369395
    },
    "spotState": {
      "balances": [
        {
          "coin": "USDC",
          "token": 0,
          "total": "0.22",
          "hold": "0.0",
          "entryNtl": "0.0"
        }
      ]
    }
  }
]

​

Use cases

• Portfolio management: Monitor and manage multiple trading strategies across sub-accounts
• Risk oversight: Track exposure and performance across segregated accounts
• Account administration: Manage complex account structures for institutional users
• Consolidated reporting: Generate comprehensive reports across all sub-accounts
• Strategy monitoring: Track the performance of isolated trading strategies
• Team coordination: Manage trading activities across different team members
• Asset allocation: Understand capital distribution across sub-accounts
• Account consolidation: View aggregated positions and balances across accounts
• Spot balance tracking: Monitor spot token balances across all sub-accounts
• Perpetuals monitoring: Track perpetuals positions and margin usage across accounts
• Withdrawal planning: Check withdrawable amounts across all sub-accounts
• Multi-account analytics: Perform analysis across segregated trading environments