Get Subaccount

This endpoint retrieves detailed information for a specific subaccount, providing essential account metadata, collateral information, and cross margin summary. For detailed position information, use the getPositions endpoint. For performance analytics, use the getPerformanceHistory endpoint.

Endpoint

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

Request

Request Format

{
  "params": {
    "action": "getSubAccount",
    "subAccountId": "1867542890123456789"
  },
  "expiresAfter": 1735689900,
  "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 `"getSubAccount"`
`params.subAccountId`	string	Yes	The ID of the subaccount to retrieve

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, getOrderHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates, getWithdrawableAmounts, getFeeRate, getSnaxpotEpochTickets) do not require the nonce parameter. Only signature and optional expiresAfter are needed. :::

Response

Success Response

{
  "status": "ok",
  "response": {
    "subAccountId": "1867542890123456789",
    "masterAccountId": "1867542890123456788",
    "subAccountName": "Trading Account 1",
    "collaterals": [
      {
        "symbol": "USDC",
        "quantity": "1000.00000000",
        "withdrawable": "1000.00000000",
        "pendingWithdraw": "0.00000000",
        "adjustedCollateralValue": "1000.00000000",
        "collateralValue": "1000.00000000",
        "haircutRate": "0",
        "haircutAdjustment": "0",
        "price": "1.00000000",
        "calculatedAt": 0
      },
      {
        "symbol": "ETH",
        "quantity": "0.5000",
        "withdrawable": "0.5000",
        "pendingWithdraw": "0.0000",
        "adjustedCollateralValue": "875.00000000",
        "collateralValue": "1000.00000000",
        "haircutRate": "0.125",
        "haircutAdjustment": "125.00000000",
        "price": "2000.00000000",
        "calculatedAt": 1735689900000
      }
    ],
    "crossMarginSummary": {
      "accountValue": "6750.50",
      "availableMargin": "2415.00",
      "totalUnrealizedPnl": "75.00",
      "maintenanceMargin": "1207.50",
      "initialMargin": "2415.00",
      "withdrawable": "4335.50",
      "adjustedAccountValue": "6750.50",
      "debt": "0.00"
    },
    "positions": [],
    "marketPreferences": {
      "leverages": {
        "BTC-USDT": 20,
        "ETH-USDT": 10
      }
    },
    "feeRates": {
      "makerFeeRate": "0.0002",
      "takerFeeRate": "0.0005",
      "tierName": "Regular User"
    },
    "accountLimits": {
      "maxBorrowCapacity": "100000.00",
      "maxOrdersPerMarket": 200,
      "maxSubAccounts": 10,
      "maxTotalOrders": 1000
    }
  },
  "request_id": "5ccf215d37e3ae6d"
}

Subaccount Object

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.maxBorrowCapacity`	string	Maximum borrow capacity in USD
`accountLimits.maxOrdersPerMarket`	integer	Maximum number of open orders per market
`accountLimits.maxSubAccounts`	integer	Maximum number of subaccounts allowed for the master account
`accountLimits.maxTotalOrders`	integer	Maximum total number of open orders across all markets

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)
`haircutRate`	string	Haircut rate applied to this collateral (e.g., "0.1" = 10% discount)
`haircutAdjustment`	string	Absolute haircut adjustment amount in USD
`price`	string	Collateral token price in USD at time of calculation
`calculatedAt`	integer	Unix timestamp (milliseconds) when price was last calculated; `0` for USDT

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
`debt`	string	Outstanding debt in the account

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
Account Metadata: Provides complete account information for the specified subaccount
Collateral Overview: Shows all assets held in the subaccount
Master Account Relationships: Identifies the master account hierarchy if applicable
Margin Overview: Provides comprehensive margin and balance data across all positions
Complementary Data: Use with getPositions for position details and getPerformanceHistory for performance analytics

Code Examples

Get Specific Subaccount

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

Response includes:

Detailed subaccount metadata
Collateral balances
Cross margin summary
Market preferences
Position information (if applicable)

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: "getSubAccount",
  expiresAfter: 0  // Optional, use 0 for no expiration
};
 
const signature = await signer._signTypedData(domain, types, message);

Related Endpoints

Get Positions - Get positions for a subaccount
Get Performance History - View trading performance
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.