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. Must use EIP-55 checksum casing — non-checksummed addresses return a 400 error with the expected checksummed form.
`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

Invalid address format:

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

EIP-55 checksum mismatch:

{
  "id": "subaccounts-1",
  "status": 400,
  "result": null,
  "error": {
    "code": 400,
    "message": "walletAddress must use EIP-55 checksum casing; expected 0x742D35CC6634c0532925A3b844BC9E7595F0BEb0"
  }
}

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: '0x742D35CC6634c0532925A3b844BC9E7595F0BEb0'
    }
  }));
};
 
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": "0x742D35CC6634c0532925A3b844BC9E7595F0BEb0",
    "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: '0x742D35CC6634c0532925A3b844BC9E7595F0BEb0'
    }
  }));
};
 
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
EIP-55 Required: walletAddress must use EIP-55 checksum casing. Lowercase, uppercase, or any other non-checksummed form returns a 400 error that includes the expected checksummed address.
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

// EIP-55 checksummed address (required)
"0x742D35CC6634c0532925A3b844BC9E7595F0BEb0"

Invalid Formats

// Lowercase — rejected with EIP-55 checksum error
"0x742d35cc6634c0532925a3b844bc9e7595f0beb0"
 
// Uppercase — rejected with EIP-55 checksum error
"0x742D35CC6634C0532925A3B844BC9E7595F0BEB0"
 
// Missing 0x prefix
"742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
 
// Too short
"0x742d35Cc6634C0532925a3b844Bc9e7595"
 
// Invalid characters
"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEg0"

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)
Address must use EIP-55 checksum casing — non-checksummed addresses are rejected
Invalid addresses will return a 400 error

Error Handling

Error	Cause	Solution
`Invalid wallet address format`	Address is not a valid Ethereum hex address	Verify format: 0x prefix + 40 hex characters
`walletAddress must use EIP-55 checksum casing; expected 0x...`	Address format is valid but casing does not match EIP-55 checksum	Use the checksummed address returned in the error message, or compute EIP-55 checksum before sending
`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