getSubAccountIds

Returns all subaccount IDs associated with a wallet address.

Endpoint

POST https://papi.synthetix.io/v1/info

Request

Request Format

{
  "params": {
    "action": "getSubAccountIds",
    "walletAddress": "0x742D35CC6634c0532925A3b844BC9E7595F0BEb0"
  }
}

Request Parameters

Parameter	Type	Required	Description
`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 separately. Defaults to `false` (returns owned IDs as a flat array).

Response

Success Response (default)

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

{
  "status": "ok",
  "response": [
    "1867542890123456789",
    "1867542890123456790",
    "1867542890123456791"
  ],
  "request_id": "5ccf215d37e3ae6d"
}

Success Response (with `includeDelegations: true`)

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

{
  "status": "ok",
  "response": {
    "subAccountIds": [
      "1867542890123456789",
      "1867542890123456790"
    ],
    "delegatedSubAccountIds": [
      "1867542890123456800"
    ]
  },
  "request_id": "5ccf215d37e3ae6d"
}

Response Fields

Default response (includeDelegations omitted or false):

The response is an array of subaccount ID strings. Each ID is a uint64 represented as a string for precision.

With includeDelegations: true:

Field	Type	Description
`response.subAccountIds`	string[]	Subaccount IDs owned by the wallet address
`response.delegatedSubAccountIds`	string[]	Subaccount IDs for which the wallet address has been granted delegate access

All IDs are uint64 values represented as strings for precision.

Error Response

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes

The following 400 errors are specific to this endpoint:

Error message	HTTP status	Cause
`walletAddress must use EIP-55 checksum casing; expected {address}`	400	Address is valid hex but does not match EIP-55 checksum casing. The expected checksummed form is returned in the message.
`Invalid wallet address format`	400	Address is not a valid Ethereum hex address (must be `0x` + 40 hex characters).
`Invalid request body`	400	`walletAddress` is missing from the request params.

Breaking Changes

EIP-55 checksum enforcement for `walletAddress`

walletAddress now requires EIP-55 checksum casing. Valid hex addresses that do not match the EIP-55 checksum are rejected with HTTP 400. The error response includes the expected checksummed form.

Before: Lowercase, uppercase, or arbitrary mixed-case addresses were accepted.

After: Only EIP-55 checksummed addresses are accepted.

// Before (rejected)
{ "walletAddress": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0" }
 
// After (accepted)
{ "walletAddress": "0x742D35CC6634c0532925A3b844BC9E7595F0BEb0" }

Migration: Compute the EIP-55 checksummed address before sending:

// ethers.js v6
import { getAddress } from 'ethers';
const checksummed = getAddress('0x742d35cc6634c0532925a3b844bc9e7595f0beb0');
// → '0x742D35CC6634c0532925A3b844BC9E7595F0BEb0'
 
// web3.js
const checksummed = web3.utils.toChecksumAddress('0x742d35cc6634c0532925a3b844bc9e7595f0beb0');
// → '0x742D35CC6634c0532925A3b844BC9E7595F0BEb0'

Code Examples

TypeScript — owned IDs (default)

const response = await fetch('https://papi.synthetix.io/v1/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    params: {
      action: 'getSubAccountIds',
      walletAddress: '0x742D35CC6634c0532925A3b844BC9E7595F0BEb0'
    }
  })
});
 
const data = await response.json();
console.log('Subaccounts:', data.response);  // Array of subaccount IDs

TypeScript — owned and delegated IDs

const response = await fetch('https://papi.synthetix.io/v1/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    params: {
      action: 'getSubAccountIds',
      walletAddress: '0x742D35CC6634c0532925A3b844BC9E7595F0BEb0',
      includeDelegations: true
    }
  })
});
 
const data = await response.json();
console.log('Owned subaccounts:', data.response.subAccountIds);
console.log('Delegated subaccounts:', data.response.delegatedSubAccountIds);

Implementation Notes

No authentication required (public endpoint)
Returns all subaccounts ever created for the wallet address
Subaccount IDs are returned as strings to preserve uint64 precision
includeDelegations: true triggers a parallel lookup of delegations for the wallet address
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 (e.g., "walletAddress must use EIP-55 checksum casing; expected 0xAbc...")