POST
/
4f8d8f4040bdacd1577bff8058438274
/
info
info (subAccounts)
curl --request POST \
  --url https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "subAccounts",
  "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036"
}'
[
  {
    "subAccount": "<string>",
    "name": "<string>",
    "master": "<string>",
    "clearinghouseState": {
      "accountValue": "<string>",
      "totalRawUsd": "<string>",
      "totalMarginUsed": "<string>"
    },
    "positions": [
      {
        "coin": "<string>",
        "size": "<string>",
        "unrealizedPnl": "<string>"
      }
    ],
    "createdTime": 123,
    "isActive": true
  }
]
The info endpoint with type: "subAccounts" retrieves information about all sub-accounts associated with a master account on the Hyperliquid exchange. This endpoint provides comprehensive data about sub-account configurations, balances, positions, and trading activity for advanced account management and portfolio segregation.
Get your own node endpoint todayStart for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.

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

The response is an array of sub-account objects with detailed information about each sub-account:

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

Sub-account benefits:
  • 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
Account hierarchy:
  • 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
Use cases:
  • 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

Shell
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

The info endpoint with type: "subAccounts" is essential for applications that need to:
  • 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
This endpoint provides comprehensive visibility into both perpetuals and spot trading states across all sub-accounts, making it essential for sophisticated account management and multi-strategy trading operations.

Body

application/json

Response

200 - application/json

List of sub-accounts associated with the user

List of sub-account details and their configurations