Create Subaccount

Create a new trading subaccount under the authenticated wallet address. Subaccounts allow for isolated trading strategies, separate margin management, and organized position tracking within a single master account.

Endpoint

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

Request

Request Format

{
  "params": {
    "action": "createSubaccount",
    "name": "Trading Bot Strategy"
  },
  "nonce": 1735689600000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Parameters object containing method details
`params.action`	string	Yes	Must be `"createSubaccount"`
`params.name`	string	No	Optional display name for the new subaccount (max 50 chars)
`nonce`	integer (uint64)	Yes	Unix milliseconds timestamp, monotonically increasing
`signature`	object	Yes	EIP-712 signature for wallet authentication

Authentication

This endpoint authenticates at the wallet level rather than requiring an existing subAccountId. The signature must be created by the wallet owner to authorize subaccount creation.

Naming Guidelines

Optional Parameter: Name can be omitted for system-generated naming
Descriptive Names: Use clear, meaningful names for easy identification when provided
Character Limit: Maximum 50 characters when specified
Default Behavior: If no name provided, system may generate a default identifier
Strategy-Based: Consider naming based on trading strategy or purpose

Examples:

"Main Trading"
"DCA Strategy"
"Arbitrage Bot"
"Risk Management"
"" (empty string) - System handles default naming

Response

Success Response (New Account)

When a subaccount is first created, only subAccountId and subAccountName are populated. All other fields return zero/null values:

{
  "status": "ok",
  "response": {
    "subAccountId": "1867542890123456790",
    "masterAccountId": null,
    "subAccountName": "Trading Bot Strategy",
    "collaterals": null,
    "crossMarginSummary": {
      "accountValue": "0",
      "availableMargin": "0",
      "totalUnrealizedPnl": "0",
      "maintenanceMargin": "0",
      "initialMargin": "0",
      "withdrawable": "0",
      "adjustedAccountValue": "0"
    },
    "positions": null,
    "marketPreferences": {
      "leverages": null
    },
    "feeRates": {
      "makerFeeRate": "0",
      "takerFeeRate": "0",
      "tierName": ""
    }
  },
  "request_id": "5ccf215d37e3ae6d"
}

Example Response (After Deposits/Trading)

After depositing collateral and opening positions, the account will have populated values:

{
  "status": "ok",
  "response": {
    "subAccountId": "1867542890123456790",
    "masterAccountId": null,
    "subAccountName": "Trading Bot Strategy",
    "collaterals": [
      {
        "symbol": "USDT",
        "quantity": "10000.00",
        "withdrawable": "5000.00",
        "pendingWithdraw": "0"
      }
    ],
    "crossMarginSummary": {
      "accountValue": "10500.00",
      "availableMargin": "5250.00",
      "totalUnrealizedPnl": "500.00",
      "maintenanceMargin": "2000.00",
      "initialMargin": "5000.00",
      "withdrawable": "5000.00",
      "adjustedAccountValue": "10500.00"
    },
    "positions": [
      {
        "symbol": "BTC-USDT",
        "side": "long",
        "entryPrice": "45000.00",
        "quantity": "0.1",
        "pnl": "0",
        "upnl": "500.00",
        "usedMargin": "4500.00",
        "maintenanceMargin": "2000.00",
        "liquidationPrice": "40000.00"
      }
    ],
    "marketPreferences": {
      "leverages": {
        "BTC-USDT": 10,
        "ETH-USDT": 5
      }
    },
    "feeRates": {
      "makerFeeRate": "0.0002",
      "takerFeeRate": "0.0005",
      "tierName": "VIP1"
    }
  },
  "request_id": "5ccf215d37e3ae6d"
}

Response Structure

Response Fields

Field	Type	Description
`subAccountId`	string	System-generated unique identifier for the new subaccount (populated)
`masterAccountId`	string \| null	Master account ID (returns `null`)
`subAccountName`	string	Display name provided in request (or empty if not specified) (populated)
`collaterals`	array \| null	Collateral balances (returns `null` for new accounts)
`crossMarginSummary`	object	Cross-margin account summary (returns empty strings for new accounts)
`positions`	array \| null	Open positions (returns `null` for new accounts)
`marketPreferences`	object	Market-specific preferences like leverage (returns empty for new accounts)
`feeRates`	object	Fee rate information (returns empty strings for new accounts)

Initial State

Populated Fields: Only subAccountId and subAccountName are populated upon creation
Zero/Null Values: Other fields are returned with zero or null values since the account has no positions or collaterals yet
Active Status: Subaccount is immediately available for trading
Full Functionality: All trading features are enabled upon creation
Additional Details: Use Get Subaccount after deposits/trades to retrieve populated account information including positions and collaterals

Error Response

{
  "status": "error",
  "error": {
    "message": "Failed to create subaccount",
    "code": "INTERNAL_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Common Error Cases

{
  "status": "error",
  "error": {
    "message": "Subaccount limit reached",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d"
}

{
  "status": "error",
  "error": {
    "message": "Invalid subaccount name",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Code Examples

Create Basic Subaccount

{
  "params": {
    "action": "createSubaccount",
    "name": "Main Trading"
  },
  "nonce": 1735689600000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Create Strategy-Specific Subaccount

{
  "params": {
    "action": "createSubaccount",
    "name": "Grid Trading Bot"
  },
  "nonce": 1735689600001,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Implementation Notes

Wallet-level authentication required (no existing subAccountId needed)
Subaccount name parameter is optional and accepts empty string for system-generated naming
Name length must not exceed 50 characters when provided
Account creation limits may apply per platform configuration
New subaccounts are immediately available for trading operations
Each subaccount inherits master wallet security and authorization settings

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

:::note SubAccountAction Exception SubAccountAction endpoints (getPositions, getOpenOrders, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getDelegatedSigners, getBalanceUpdates) do not require a nonce. Only the signature and optional expiresAfter parameters are needed. :::

Error Handling

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