Get SubAccount IDs (WebSocket)

Returns all subaccount IDs associated with a wallet address through the WebSocket connection. This is a public endpoint that allows looking up subaccounts without authentication.

Endpoint

ws.send() wss://api.synthetix.io/v1/ws/info

Request

Request Format

{
  "id": "subaccounts-1",
  "method": "post",
  "params": {
    "action": "getSubAccountIds",
    "walletAddress": "0x1234567890123456789012345678901234567890"
  }
}

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Client-generated unique request identifier
`method`	string	Yes	Must be `"post"`
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"getSubAccountIds"`
`params.walletAddress`	string	Yes	Ethereum wallet address to query
`params.includeDelegations`	boolean	No	When `true`, returns owned and delegated subaccount IDs as separate fields. Defaults to `false` (flat array of owned IDs).

Response

Success Response (default)

When includeDelegations is omitted or false, the response is a flat array of owned subaccount IDs:

{
  "id": "subaccounts-1",
  "status": 200,
  "result": {
    "response": [
      "1867542890123456789",
      "1867542890123456790",
      "1867542890123456791"
    ],
    "status": "success"
  }
}

Success Response (with `includeDelegations: true`)

When includeDelegations is true, result.response is an object with owned and delegated IDs listed separately:

{
  "id": "subaccounts-1",
  "status": 200,
  "result": {
    "response": {
      "subAccountIds": [
        "1867542890123456789",
        "1867542890123456790"
      ],
      "delegatedSubAccountIds": [
        "1867542890123456800"
      ]
    },
    "status": "success"
  }
}

Response Fields

Default response (includeDelegations omitted or false):

Field	Type	Description
`result.response`	string[]	Array of owned subaccount ID strings (uint64 as strings for precision)
`result.status`	string	Always `"success"` for successful responses

With includeDelegations: true:

Field	Type	Description
`result.response.subAccountIds`	string[]	Subaccount IDs owned by the wallet address
`result.response.delegatedSubAccountIds`	string[]	Subaccount IDs for which the wallet has delegate access
`result.status`	string	Always `"success"` for successful responses

Error Response

{
  "id": "subaccounts-1",
  "status": 400,
  "result": null,
  "error": {
    "code": 400,
    "message": "Invalid wallet address format"
  }
}

WebSocket Connection Example

const ws = new WebSocket('wss://papi.synthetix.io/v1/ws/info');
 
ws.onopen = () => {
  // Request subaccount IDs for a wallet
  ws.send(JSON.stringify({
    id: 'subaccounts-1',
    method: 'post',
    params: {
      action: 'getSubAccountIds',
      walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
    }
  }));
};
 
ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
 
  if (response.id === 'subaccounts-1' && response.status === 200) {
    const subaccountIds = response.result.response;
    console.log('Subaccount IDs:', subaccountIds);
    console.log(`Found ${subaccountIds.length} subaccounts`);
    subaccountIds.forEach((id, index) => {
      console.log(`  ${index + 1}. ${id}`);
    });
  }
};

Examples

Lookup Subaccounts for Wallet

{
  "id": "lookup-1",
  "method": "post",
  "params": {
    "action": "getSubAccountIds",
    "walletAddress": "0x1234567890123456789012345678901234567890"
  }
}

Lookup Owned and Delegated Subaccounts

{
  "id": "lookup-delegated-1",
  "method": "post",
  "params": {
    "action": "getSubAccountIds",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "includeDelegations": true
  }
}

Check if Wallet Has Subaccounts

const ws = new WebSocket('wss://papi.synthetix.io/v1/ws/info');
 
ws.onopen = () => {
  ws.send(JSON.stringify({
    id: 'check-subaccounts',
    method: 'post',
    params: {
      action: 'getSubAccountIds',
      walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
    }
  }));
};
 
ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
 
  if (response.id === 'check-subaccounts' && response.status === 200) {
    const subaccountIds = response.result.response;
    const hasSubaccounts = subaccountIds.length > 0;
    console.log(`Wallet has subaccounts: ${hasSubaccounts}`);
    if (hasSubaccounts) {
      console.log(`Total subaccounts: ${subaccountIds.length}`);
    }
  }
};

Implementation Notes

Public Data: No authentication required for this endpoint
Wallet Address Required: Must provide a valid Ethereum address
All Subaccounts: Returns all subaccounts ever created for the wallet address
ID Format: Subaccount IDs are returned as strings to preserve uint64 precision
Case Insensitive: Wallet addresses are normalized (case doesn't matter)
Historical Data: Includes all subaccounts, even if no longer active
Delegation Lookup: When includeDelegations: true, a parallel lookup for delegated subaccounts is performed

Use Cases

Account Discovery

Find all subaccounts associated with a wallet
Verify subaccount ownership
List available trading accounts

Delegation-Aware Lookups

Enumerate all subaccounts a delegate address can act on
Build interfaces that surface both owned and delegated accounts

Integration Support

Allow users to select from existing subaccounts
Validate subaccount IDs before operations
Display account lists in trading interfaces

Account Management

Check if wallet has trading accounts
Enumerate subaccounts for migration
Audit subaccount creation

Address Format Validation

Valid Formats

// Checksummed address (preferred)
"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
 
// Lowercase
"0x742d35cc6634c0532925a3b844bc9e7595f0beb"
 
// Uppercase
"0x742D35CC6634C0532925A3B844BC9E7595F0BEB"

Invalid Formats

// Missing 0x prefix
"742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
 
// Too short
"0x742d35Cc6634C0532925a3b844Bc9e7595"
 
// Invalid characters
"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEg"

Performance Considerations

Low Latency: WebSocket connection provides faster response times than REST
Persistent Connection: Reuse the same connection for multiple lookups
Lightweight: Returns only subaccount IDs (minimal data transfer)
Efficient Lookup: Fast database query for subaccount enumeration

Validation Rules

No authentication required (public Info WebSocket)
Wallet address parameter is required
Address must be a valid Ethereum hex address (0x + 40 hex characters)
Invalid addresses will return a 400 error

Error Handling

Error	Cause	Solution
`Invalid wallet address format`	Address not a valid Ethereum address	Verify address format (0x + 40 hex chars)
`Invalid request body`	Missing walletAddress parameter	Include walletAddress in params

Related Endpoints

Get Subaccount - Detailed subaccount information (authenticated)
Create Subaccount - Create new subaccount
REST Alternative - HTTP request for subaccount IDs