Hyperliquid subAccounts Info Endpoint: List Subaccount Addresses (Python Example)

The request is documented in the Hyperliquid info endpoint reference.

Request

Use the following HTTP request:

• Method: POST
• URL: https://api.hyperliquid.xyz/info
• Header: Content-Type: application/json
• Body:

{
  "type": "subAccounts",
  "user": "0x0000000000000000000000000000000000000000"
}

The user field must be a 42-character hexadecimal address. The documentation notes that you should pass the actual address of the master or sub-account you are querying. A common pitfall is using an agent wallet address, which can lead to an empty result.

Response shape

The endpoint returns an array. Each item represents a subaccount and includes the fields shown in the documentation example:

[
  {
    "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"
        }
      ]
    }
  }
]

Field reference

Python example

This reference example uses a normal HTTP POST request to the documented endpoint. It is not a live-account test.

import requests


def list_subaccounts(user_address: str) -> list[dict]:
    response = requests.post(
        "https://api.hyperliquid.xyz/info",
        json={
            "type": "subAccounts",
            "user": user_address,
        },
        headers={"Content-Type": "application/json"},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()


## Example:
## subaccounts = list_subaccounts("0x0000000000000000000000000000000000000000")
## for item in subaccounts:
##     print(item["name"], item["subAccountUser"], item["master"])

Troubleshooting notes

• If the result is empty, check that user is the actual account address rather than an agent wallet address.
• If you need to confirm whether an address is a subaccount, see the Hyperliquid userRole info endpoint.
• For API error handling, see the Hyperliquid API error responses guide.
• For request limits, see Hyperliquid API rate limits.

Create a Hyperliquid account

This is an affiliate link. If you sign up, we may receive a commission. The referral page lists a 4% fee discount for the first $25M of volume per account; Vaults and sub-accounts are excluded.

Continue with Hyperliquid

Browse the Hyperliquid guide hub for the complete user journey.