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*	Unix milliseconds timestamp (must be monotonically increasing)
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	uint64	No	Unix seconds 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, getDelegatedSigners, getBalanceUpdates) 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"
      },
      {
        "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"
    }
  },
  "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")

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

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

Error Response

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

Error	Description
Invalid signature	EIP-712 signature validation failed
Invalid market symbol	Market symbol not recognized
Nonce already used	Nonce must be greater than previous value
Rate limit exceeded	Too many requests in time window
Request expired	`expiresAfter` timestamp has passed

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.