subAccounts

Get sub-account information for a user, including linked accounts, permissions, and relationship details.

When to Use This Endpoint

The subAccounts endpoint is essential for:

• Account Management — View all sub-accounts linked to a main account
• Permission Tracking — Monitor sub-account permissions and access levels
• Portfolio Organization — Organize trading strategies across multiple accounts
• Access Control — Manage delegation and trading permissions

Request

Endpoint

POST https://api-hyperliquid-mainnet-info.n.dwellir.com/info

Headers

Header	Value	Required
Content-Type	application/json	Yes
X-Api-Key	Your API key	Yes

Parameters

Parameter	Type	Required	Description
type	string	Yes	Must be "subAccounts"
user	string	Yes	User's Ethereum wallet address

Example Request

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

Response

Success Response

Returns sub-account information for the specified user.

{
  "subAccounts": []
}

Response Fields

Field	Type	Description
subAccounts	array	Array of sub-account records with addresses and permissions

Code Examples

cURL

curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "subAccounts",
    "user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f"
  }'

JavaScript

const ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info';
const API_KEY = 'your-api-key-here';

async function getSubAccounts(userAddress) {
  const response = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY
    },
    body: JSON.stringify({
      type: 'subAccounts',
      user: userAddress
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  return await response.json();
}

// Usage
const accounts = await getSubAccounts('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
console.log(`Total sub-accounts: ${accounts.subAccounts.length}`);

Python

import requests
from typing import Dict

ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info'
API_KEY = 'your-api-key-here'

def get_sub_accounts(user_address: str) -> Dict:
    """Get user sub-account information"""
    response = requests.post(
        ENDPOINT,
        json={
            'type': 'subAccounts',
            'user': user_address
        },
        headers={
            'Content-Type': 'application/json',
            'X-Api-Key': API_KEY
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

# Usage
accounts = get_sub_accounts('0x63E8c7C149556D5f34F833419A287bb9Ef81487f')
print(f"Total sub-accounts: {len(accounts['subAccounts'])}")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const (
    Endpoint = "https://api-hyperliquid-mainnet-info.n.dwellir.com/info"
    APIKey   = "your-api-key-here"
)

type SubAccountsRequest struct {
    Type string `json:"type"`
    User string `json:"user"`
}

type SubAccountsResponse struct {
    SubAccounts []interface{} `json:"subAccounts"`
}

func getSubAccounts(userAddress string) (*SubAccountsResponse, error) {
    reqBody, _ := json.Marshal(SubAccountsRequest{
        Type: "subAccounts",
        User: userAddress,
    })

    req, _ := http.NewRequest("POST", Endpoint, bytes.NewBuffer(reqBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Api-Key", APIKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var result SubAccountsResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func main() {
    accounts, err := getSubAccounts("0x63E8c7C149556D5f34F833419A287bb9Ef81487f")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Total sub-accounts: %d\n", len(accounts.SubAccounts))
}

Common Use Cases

1. List All Sub-Accounts

Display all sub-accounts for a user:

async function listSubAccounts(userAddress) {
  const data = await getSubAccounts(userAddress);

  console.log('=== Sub-Accounts ===\n');
  console.log(`Total sub-accounts: ${data.subAccounts.length}`);

  if (data.subAccounts.length === 0) {
    console.log('No sub-accounts configured');
  } else {
    console.log('Sub-accounts are configured');
  }
}

// Usage
await listSubAccounts('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');

2. Check Account Structure

Verify account hierarchy:

async function checkAccountStructure(userAddress) {
  const data = await getSubAccounts(userAddress);

  return {
    mainAccount: userAddress,
    subAccountCount: data.subAccounts.length,
    hasSubAccounts: data.subAccounts.length > 0,
    timestamp: new Date().toISOString()
  };
}

// Usage
const structure = await checkAccountStructure('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
console.log('Account structure:', structure);

3. Build Account Management Dashboard

Create a dashboard for account management:

async function getAccountDashboard(userAddress) {
  try {
    const data = await getSubAccounts(userAddress);

    return {
      status: 'success',
      mainAccount: userAddress,
      subAccounts: data.subAccounts,
      totalAccounts: 1 + data.subAccounts.length, // main + sub-accounts
      lastUpdated: new Date().toISOString()
    };
  } catch (error) {
    return {
      status: 'error',
      error: error.message
    };
  }
}

// Usage
const dashboard = await getAccountDashboard('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
console.log('Account Dashboard:', dashboard);

4. Monitor Account Changes

Track sub-account additions or removals:

class SubAccountMonitor {
  constructor(userAddress) {
    this.userAddress = userAddress;
    this.lastKnownCount = null;
  }

  async checkForChanges() {
    const data = await getSubAccounts(this.userAddress);
    const currentCount = data.subAccounts.length;

    if (this.lastKnownCount !== null) {
      const change = currentCount - this.lastKnownCount;

      if (change > 0) {
        console.log(`${change} sub-account(s) added`);
      } else if (change < 0) {
        console.log(`${Math.abs(change)} sub-account(s) removed`);
      }
    }

    this.lastKnownCount = currentCount;

    return {
      currentCount: currentCount,
      changed: this.lastKnownCount !== null && currentCount !== this.lastKnownCount
    };
  }
}

// Usage
const monitor = new SubAccountMonitor('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
await monitor.checkForChanges();

5. Validate Sub-Account Access

Check if sub-accounts are properly configured:

async function validateSubAccountAccess(userAddress) {
  const data = await getSubAccounts(userAddress);

  const validation = {
    isConfigured: data.subAccounts.length > 0,
    accountCount: data.subAccounts.length,
    status: data.subAccounts.length > 0 ? 'configured' : 'unconfigured',
    recommendation: data.subAccounts.length === 0
      ? 'Consider setting up sub-accounts for strategy separation'
      : 'Sub-accounts are active'
  };

  console.log('Sub-Account Validation:', validation);
  return validation;
}

Error Handling

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid API key	Verify your API key is correct
400 Bad Request	Missing or invalid user address	Ensure valid Ethereum address format
429 Too Many Requests	Rate limit exceeded	Implement request throttling
500 Internal Server Error	Server issue	Retry with exponential backoff

Error Response Example

{
  "error": "Missing required parameter: user",
  "code": "MISSING_PARAMETER"
}

Robust Error Handling

async function safeGetSubAccounts(userAddress, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await getSubAccounts(userAddress);
    } catch (error) {
      if (error.response?.status === 429) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else if (error.response?.status === 400) {
        throw new Error('Invalid user address');
      } else if (i === maxRetries - 1) {
        throw error;
      }
    }
  }
}

Best Practices

1. Validate addresses — Ensure user addresses are valid Ethereum addresses
2. Cache data — Cache sub-account data for several minutes
3. Handle empty states — Account for users without sub-accounts
4. Monitor changes — Track sub-account additions/removals over time
5. Organize strategies — Use sub-accounts to separate different trading strategies

Related Endpoints

• clearinghouseState — Get account state for each account
• openOrders — Get orders across accounts
• userFees — Get fee information
• extraAgents — Get agent information

---

Manage your Hyperliquid sub-accounts with Dwellir's HyperCore Info Endpoint. Get your API key →