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

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

{
  "status": "ok",
  "response": {
    "subAccountId": "1867542890123456790",
    "subAccountName": "Trading Bot Strategy"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Response Structure

Response Fields

Initial State

• Minimal Response: Returns only the essential identifiers for the new subaccount
• Active Status: Subaccount is immediately available for trading
• Full Functionality: All trading features are enabled upon creation
• Additional Details: Use Get Subaccount to retrieve complete account information including positions and collaterals

Error Response

{
  "status": "error",
  "error": {
    "message": "Failed to create subaccount",
    "code": "INTERNAL_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Common Error Cases

{
  "status": "error",
  "error": {
    "message": "Subaccount limit reached",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

{
  "status": "error",
  "error": {
    "message": "Invalid subaccount name",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

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

Error Handling