Managing Subaccounts

How to create, configure, and manage subaccounts using the Deribit API.

Subaccounts allow you to organize trading activities, manage risk, and separate different strategies or clients under a single main account. This guide explains how to manage subaccounts programmatically using the Deribit API.

Before calling any private method you must authenticate. Please refer to API Authentication Guide for more information regarding authentication.

Overview

Subaccounts are separate trading accounts that belong to a main account. They share the same KYC verification status as the main account but operate independently for trading, positions, and wallet balances. Subaccounts are useful for:

• Risk management: Isolating different trading strategies
• Client segregation: Managing multiple clients under one account
• Organizational structure: Separating different departments or teams

Only main accounts can create and manage subaccounts. Subaccounts cannot create other subaccounts. All subaccount management operations require the account:read_write scope and must be performed from the main account.

Creating a Subaccount

To create a new subaccount, use the private/create_subaccount method. This method takes no parameters and creates a new subaccount with a default name.

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/create_subaccount",
  "params": {},
  "id": 1
}

Response

On success, the API returns an object containing:

• id - The unique subaccount ID (user ID)
• username - The default username for the subaccount
• type - Account type (e.g., “subaccount”)
• email - Email address (if assigned)
• system_name - System-generated name
• is_password - Whether password is set
• is_otp_enabled - Whether 2FA is enabled
• login_enabled - Whether login is enabled
• portfolio - Portfolio information (if available)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": 12345,
    "username": "user_1_1",
    "type": "subaccount",
    "email": null,
    "system_name": "user_1_1",
    "is_password": false,
    "is_otp_enabled": false,
    "login_enabled": true,
    "portfolio": {
      "equity": 0,
      "available_funds": 0,
      "maintenance_margin": 0
    }
  }
}

The subaccount ID (id) is required for all subsequent subaccount management operations. Store this value for future reference.

Retrieving Subaccount Information

List All Subaccounts

To retrieve information about all subaccounts, use the private/get_subaccounts method.

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/get_subaccounts",
  "params": {
    "with_portfolio": true
  },
  "id": 2
}

Parameters

• with_portfolio (optional): Set to true to include portfolio information (equity, available funds, maintenance margin). Defaults to false.

Response

The response includes an array of subaccounts, each containing:

• id - Subaccount ID
• username - Username
• email - Email address (if assigned)
• login_enabled - Whether login is enabled
• notifications_enabled - Whether notifications are enabled
• portfolio - Portfolio information (if with_portfolio is true)

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": [
    {
      "id": 12345,
      "username": "user_1_1",
      "email": "[e-mail]",
      "login_enabled": true,
      "notifications_enabled": true,
      "portfolio": {
        "equity": 10000.5,
        "available_funds": 9500.0,
        "maintenance_margin": 500.5
      }
    },
    {
      "id": 12346,
      "username": "user_1_2",
      "email": null,
      "login_enabled": false,
      "notifications_enabled": false,
      "portfolio": {
        "equity": 5000.0,
        "available_funds": 5000.0,
        "maintenance_margin": 0.0
      }
    }
  ]
}

Get Subaccount Positions

To retrieve positions and trading details for all subaccounts, use the private/get_subaccounts_details method.

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/get_subaccounts_details",
  "params": {
    "currency": "BTC",
    "with_open_orders": true
  },
  "id": 3
}

Parameters

• currency (required): The currency symbol (e.g., “BTC”, “ETH”)
• with_open_orders (optional): Set to true to include open orders. Defaults to false.

Response

Returns detailed information including positions, balances, and optionally open orders for all subaccounts in the specified currency.

Configuring Subaccount Settings

Change Subaccount Name

To change the display name of a subaccount, use the private/change_subaccount_name method.

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/change_subaccount_name",
  "params": {
    "sid": 12345,
    "name": "Trading Strategy A"
  },
  "id": 4
}

Parameters

• sid (required): The subaccount ID
• name (required): The new display name

Assign Email Address

To assign an email address to a subaccount, use the private/set_email_for_subaccount method. The subaccount user will receive a confirmation email.

This operation requires Two-Factor Authentication (2FA). See Security Keys for details.

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/set_email_for_subaccount",
  "params": {
    "sid": 12345,
    "email": "[e-mail]"
  },
  "id": 5
}

Parameters

• sid (required): The subaccount ID
• email (required): The email address to assign

Enable or Disable Login

To control whether a subaccount can log in through the web interface, use the private/toggle_subaccount_login method.

This operation requires Two-Factor Authentication (2FA). If login is disabled and an active session exists, that session will be terminated immediately.

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/toggle_subaccount_login",
  "params": {
    "sid": 12345,
    "state": "enable"
  },
  "id": 6
}

Parameters

• sid (required): The subaccount ID
• state (required): Either "enable" or "disable"

Enable or Disable Notifications

To control whether a subaccount receives email notifications, use the private/toggle_notifications_from_subaccount method.

This operation requires Two-Factor Authentication (2FA).

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/toggle_notifications_from_subaccount",
  "params": {
    "sid": 12345,
    "state": true
  },
  "id": 7
}

Parameters

• sid (required): The subaccount ID
• state (required): true to enable notifications, false to disable

Switching Between Subaccounts

To perform operations on behalf of a subaccount, you need to switch your authentication context using the public/exchange_token method.

Example Request

{
  "jsonrpc": "2.0",
  "method": "public/exchange_token",
  "params": {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "subaccount_id": 12345
  },
  "id": 8
}

Response

The API returns a new access token and refresh token for the specified subaccount:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "access_token": "NEW_ACCESS_TOKEN",
    "refresh_token": "NEW_REFRESH_TOKEN",
    "expires_in": 3600,
    "token_type": "bearer"
  }
}

After switching to a subaccount context, all subsequent API calls will operate on that subaccount’s data until you switch back or authenticate with a different token.

Accessing Subaccount Data via Other Endpoints

Many API endpoints support accessing subaccount data by including the subaccount_id parameter. This allows you to query subaccount information without switching authentication context.

Examples

Get Subaccount Positions

{
  "jsonrpc": "2.0",
  "method": "private/get_positions",
  "params": {
    "currency": "BTC",
    "subaccount_id": 12345
  },
  "id": 9
}

Get Subaccount Account Summary

{
  "jsonrpc": "2.0",
  "method": "private/get_account_summary",
  "params": {
    "currency": "BTC",
    "subaccount_id": 12345
  },
  "id": 10
}

Get Subaccount Trades

{
  "jsonrpc": "2.0",
  "method": "private/get_user_trades_by_currency",
  "params": {
    "currency": "BTC",
    "subaccount_id": 12345
  },
  "id": 11
}

When using the subaccount_id parameter, you must have appropriate permissions (account:read or trade:read scopes) and the request must be made from the main account.

Removing a Subaccount

To remove a subaccount, use the private/remove_subaccount method.

This operation requires Two-Factor Authentication (2FA). The subaccount must be empty (no positions, no open orders, zero balance) before it can be removed. This operation cannot be undone.

Example Request

{
  "jsonrpc": "2.0",
  "method": "private/remove_subaccount",
  "params": {
    "subaccount_id": 12345
  },
  "id": 12
}

Response

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "success": true
  }
}

Transferring Funds Between Subaccounts

Subaccounts can transfer funds between each other and to/from the main account. See the Managing Transfers via API guide for detailed information on:

• Transferring from main account to subaccount
• Transferring between subaccounts
• Checking transfer status

Moving Positions Between Subaccounts

You can move positions from one subaccount to another using the private/move_positions method. See the Moving Positions via API guide for details.

Position moves have distinct rate limiting requirements: sustained rate of 6 requests/minute. See Rate Limits for more information.

Best Practices

1. Store Subaccount IDs

Always store the subaccount ID returned when creating a subaccount. This ID is required for all management operations.

2. Use Descriptive Names

Assign meaningful names to subaccounts to easily identify their purpose (e.g., “Arbitrage Strategy”, “Client A”, “Risk Management”).

3. Manage Permissions Carefully

Ensure API keys used for subaccount management have the account:read_write scope and are created on the main account, not on subaccounts.

4. Monitor Subaccount Activity

Regularly check subaccount positions, balances, and trading activity using get_subaccounts_details and other endpoints with the subaccount_id parameter.

5. Handle 2FA Requirements

Several subaccount management operations require 2FA. Ensure your application flow supports providing the second factor when needed. See Security Keys for implementation details.

6. Empty Subaccounts Before Removal

Before removing a subaccount, ensure it has:

• No open positions
• No open orders
• Zero balance in all currencies

7. Use Appropriate Scopes

When creating API keys for subaccount operations:

• Use account:read for read-only operations (listing, viewing details)
• Use account:read_write for management operations (creating, modifying, removing)

Troubleshooting

Cannot Create Subaccount

• Error: invalid_scope or insufficient_permissions
  • Solution: Ensure your API key has the account:read_write scope and was created on the main account.

Cannot Access Subaccount Data

• Error: invalid_subaccount_id or subaccount_not_found
  • Solution: Verify the subaccount ID is correct and belongs to your main account. Use get_subaccounts to list all available subaccounts.

2FA Required Error

• Error: security_key_authorization_error (code: 13668)
  • Solution: Operations like setting email, toggling login, or removing subaccounts require 2FA. Provide the second factor in your API request. See Security Keys.

Cannot Remove Subaccount

• Error: subaccount_not_empty or similar
  • Solution: Ensure the subaccount has no positions, open orders, or balances. Transfer or close all positions and cancel all orders before removal.

Subaccount Login Disabled

• Issue: Subaccount cannot log in through web interface
  • Solution: Check if login is enabled using get_subaccounts. If disabled, use toggle_subaccount_login with state: "enable" to re-enable it.

Related Articles

• Managing Transfers via API - Transfer funds between accounts
• Moving Positions via API - Move positions between subaccounts
• API Authentication Guide - Authentication and token management
• Security Keys - Two-Factor Authentication for sensitive operations
• Creating API Key - Setting up API keys with appropriate scopes