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"
  },
  "nonce": 1735689600000,
  "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
`nonce`	integer	Yes	Current timestamp in milliseconds
`signature`	object	Yes	EIP-712 signature of the request

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 milliseconds expiration timestamp (5x rate limit on stale cancels)

Response

Success Response

{
  "status": "ok",
  "response": {
    "subAccountId": "1867542890123456789",
    "masterAccountId": "1867542890123456788",
    "subAccountName": "Trading Account 1",
    "collaterals": [
      {
        "symbol": "USDC",
        "quantity": "1000.00000000"
      },
      {
        "symbol": "ETH",
        "quantity": "0.5000"
      }
    ],
    "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
      }
    }
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

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

Collateral Object

Field	Type	Description
`symbol`	string	Collateral token symbol (e.g., "USDT")
`quantity`	string	Amount of collateral held

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",
  "timestamp": "2025-01-01T00:00:00Z"
}

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"
  },
  "nonce": 1735689600000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Response includes:

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

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.

Nonce Management

The nonce system prevents replay attacks and ensures order uniqueness:

Use current timestamp in milliseconds as nonce
Each nonce must be greater than the previous one
Recommended: Use Date.now() or equivalent
If nonce conflicts occur, increment by 1 and retry