Get Subaccounts

Retrieve all subaccounts for the authenticated wallet, including comprehensive details for each subaccount such as collateral balances, cross margin summary, positions, market preferences, fee rates, and delegated signers. This is a more comprehensive alternative to getSubAccount that returns multiple subaccounts with delegation information included.

Endpoint

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

Request

Request Format

{
  "params": {
    "action": "getSubAccounts",
    "subAccountId": "1867542890123456789"
  },
  "expiresAfter": 1735689900000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Request Parameters

Field	Type	Required	Description
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"getSubAccounts"`
`params.subAccountId`	string	Yes	The ID of a subaccount owned by the authenticated wallet

Parameter	Type	Required	Description
`nonce`	uint64	Yes*	Positive integer nonce (must be incrementing and unique per request)
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	uint64	No	Unix milliseconds expiration timestamp (5x rate limit on stale cancels)

:::info Common Parameters These are top-level request parameters. The subAccountId parameter is specified within the params object (see each endpoint's parameter table). :::

:::info SubAccountAction Endpoints Endpoints using SubAccountAction signing (getPositions, getOpenOrders, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates) do not require the nonce parameter. Only signature and optional expiresAfter are needed. :::

Response

Success Response

{
  "status": "ok",
  "response": {
    "subAccounts": [
      {
        "subAccountId": "1867542890123456789",
        "masterAccountId": "1867542890123456788",
        "subAccountName": "Trading Account 1",
        "collaterals": [
          {
            "symbol": "USDC",
            "quantity": "1000.00000000",
            "withdrawable": "1000.00000000",
            "pendingWithdraw": "0.00000000"
          },
          {
            "symbol": "ETH",
            "quantity": "0.5000",
            "withdrawable": "0.5000",
            "pendingWithdraw": "0.0000"
          }
        ],
        "crossMarginSummary": {
          "accountValue": "6750.50",
          "availableMargin": "2415.00",
          "totalUnrealizedPnl": "75.00",
          "maintenanceMargin": "1207.50",
          "initialMargin": "2415.00",
          "withdrawable": "4335.50"
          "adjustedAccountValue": "6750.50"
        },
        "positions": [],
        "marketPreferences": {
          "leverages": {
            "BTC-USDT": 20,
            "ETH-USDT": 10
          }
        },
        "feeRates": {
          "makerFeeRate": "0.0002",
          "takerFeeRate": "0.0005",
          "tierName": "Regular User"
        },
        "delegatedSigners": [
          {
            "subAccountId": "1867542890123456789",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f89590",
            "permissions": ["trading"],
            "expiresAt": null
          },
          {
            "subAccountId": "1867542890123456789",
            "walletAddress": "0x8B3a9A6F8D1e2C4E5B7A9D0F1C3E5A7B9D1F3E5A",
            "permissions": ["trading"],
            "expiresAt": 1767225600000
          }
        ]
      },
      {
        "subAccountId": "1867542890123456790",
        "masterAccountId": "1867542890123456788",
        "subAccountName": "Trading Account 2",
        "collaterals": [
          {
            "symbol": "USDC",
            "quantity": "5000.00000000",
            "withdrawable": "5000.00000000",
            "pendingWithdraw": "0.00000000"
          }
        ],
        "crossMarginSummary": {
          "accountValue": "5000.00",
          "availableMargin": "5000.00",
          "totalUnrealizedPnl": "0.00",
          "maintenanceMargin": "0.00",
          "initialMargin": "0.00",
          "withdrawable": "5000.00"
          "adjustedAccountValue": "5000.00"
        },
        "positions": [],
        "marketPreferences": {
          "leverages": {}
        },
        "feeRates": {
          "makerFeeRate": "0.0002",
          "takerFeeRate": "0.0005",
          "tierName": "Regular User"
        },
        "delegatedSigners": []
      }
    ]
  },
  "request_id": "5ccf215d37e3ae6d"
}

Response Fields

Field	Type	Description
`subAccounts`	array	Array of subaccount objects

Subaccount Object

Each subaccount in the subAccounts array includes the standard subaccount fields plus a delegatedSigners array:

Field	Type	Description
`subAccountId`	string	Unique subaccount identifier
`masterAccountId`	string \| null	ID of the master account (null if this is a master account)
`subAccountName`	string	Human-readable subaccount name
`collaterals`	array	Array of collateral assets held in this subaccount
`crossMarginSummary`	object	Cross margin summary with account value, margins, and P&L
`positions`	array	Array of open positions for this subaccount
`marketPreferences`	object	Market-specific preferences and settings
`marketPreferences.leverages`	object	Per-market leverage settings (key: symbol, value: leverage multiplier)
`feeRates`	object	Fee rate information for this subaccount
`feeRates.makerFeeRate`	string	Maker fee rate as decimal (e.g., "0.0002" for 0.02%)
`feeRates.takerFeeRate`	string	Taker fee rate as decimal (e.g., "0.0005" for 0.05%)
`feeRates.tierName`	string	Fee tier name (e.g., "Regular User", "Tier 1")
`accountLimits`	object	Account limits for this subaccount
`accountLimits.maxSubAccounts`	integer	Maximum number of subaccounts allowed for the master account

Additional Field

Field	Type	Description
`delegatedSigners`	array	Array of delegated signer objects for this subaccount

Collateral Object

Field	Type	Description
`symbol`	string	Collateral token symbol (e.g., "USDT")
`quantity`	string	Amount of collateral held
`withdrawable`	string	Amount available for withdrawal
`pendingWithdraw`	string	Amount pending withdrawal
`adjustedCollateralValue`	string	Collateral value after applying haircut discount (USD equivalent)
`collateralValue`	string	Full collateral value before haircut (USD equivalent)

Cross Margin Summary Object

Field	Type	Description
`accountValue`	string	Total account value including PnL
`availableMargin`	string	USDT amount available for new positions
`totalUnrealizedPnl`	string	Sum of all unrealized PnL
`maintenanceMargin`	string	Minimum margin required for all positions
`initialMargin`	string	Initial margin required for all positions
`withdrawable`	string	USDT amount available for withdrawal
`adjustedAccountValue`	string	Adjusted account value for margin calculations

Delegate Object

The delegate object represents a delegated signer in API responses. Note that the response uses walletAddress while EIP-712 signing uses delegateAddress.

Field	Type	Description
`subAccountId`	string	Subaccount ID this delegation applies to
`walletAddress`	string	Ethereum wallet address of the delegated signer (42-character hex format)
`permissions`	string[]	Array of permission levels granted. Currently supports: `["trading"]`
`expiresAt`	integer \| null	Unix timestamp (milliseconds) when the delegation expires. `null` indicates no expiration
`addedBy`	string \| omitted	Wallet address that created this delegation. Omitted for pre-migration records where the creator was not recorded

Example Delegate Object

{
  "subAccountId": "1867542890123456789",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f89590",
  "permissions": ["trading"],
  "expiresAt": null,
  "addedBy": "0x1111111111111111111111111111111111111111"
}

Example with Expiration

{
  "subAccountId": "1867542890123456789",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f89590",
  "permissions": ["trading"],
  "expiresAt": 1767225600000
}

Error Response

{
  "status": "error",
  "error": {
    "message": "Subaccount not found",
    "code": "NOT_FOUND"
  },
  "request_id": "5ccf215d37e3ae6d"
}

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

Subaccount Information

Account Access: Must have access rights to the specified subaccount
Delegated Access: Works with delegated signer permissions
Multiple Accounts: Returns all subaccounts associated with the authenticated wallet
Delegation Visibility: Includes delegated signers for each subaccount, unlike getSubAccount
Complementary Data: Use with getPositions for detailed position information and getPerformanceHistory for performance analytics

Code Examples

Get All Subaccounts

{
  "params": {
    "action": "getSubAccounts",
    "subAccountId": "1867542890123456789"
  },
  "expiresAfter": 1735689900000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Response includes for each subaccount:

Detailed subaccount metadata
Collateral balances
Cross margin summary
Market preferences
Position information
Fee rates
Delegated signers with permissions and expiration

EIP-712 Signature

const domain = {
  name: "Synthetix",
  version: "1",
  chainId: 1,
  verifyingContract: "0x0000000000000000000000000000000000000000"
};
 
const types = {
  SubAccountAction: [
    { name: "subAccountId", type: "uint256" },
    { name: "action", type: "string" },
    { name: "expiresAfter", type: "uint256" }
  ]
};
 
const message = {
  subAccountId: "1867542890123456789",
  action: "getSubAccounts",
  expiresAfter: 0  // Optional, use 0 for no expiration
};
 
const signature = await signer._signTypedData(domain, types, message);

Comparison with getSubAccount

Feature	`getSubAccount`	`getSubAccounts`
Returns	Single subaccount	All subaccounts for the wallet
Delegated Signers	Not included	Included for each subaccount
Use Case	Specific account lookup	Full account overview with delegation info

Related Endpoints

Get Subaccount - Get a single subaccount
Get Delegated Signers - Get delegated signers for a single subaccount
Get Positions - Get positions for a subaccount
Get Balance Updates - Track balance changes

:::info Rate Limits The Synthetix API enforces rate limits to ensure fair usage and system stability:

Order Placement: 100 orders per second per subaccount
WebSocket Connections: 100 connections per IP address
WebSocket Subscriptions: 1000 subscriptions per IP address

See Rate Limits for detailed information and best practices. :::

Signing

All trading methods are signed using EIP-712. Each successful trading request will contain:

A piece of structured data that includes the sender address
A signature of the hash of that structured data, signed by the sender

For detailed information on EIP-712 signing, see EIP-712 Signing.