What’s New with Sub Accounts?

Terminology for this document:
Multi-account: the base name for the idea of having two accounts that have a parent-child relationship
Sub Account: the new Sub Account feature we have built
Linked Account: the legacy multi-account feature

Previously, BitMEX had a multi-account feature - Linked accounts - that allowed traders to register with a new account and then request our support team to link their main account to a new account.

The feature set was somewhat limited.

While you were able to transfer funds between accounts instantly and for free, and all linked accounts were taken in aggregate when calculating fee tiers, you could transfer to your linked accounts, but needed to authenticate the linked account to transfer funds back.

Moreover, to trade with multiple accounts, you needed to log in to both accounts independently. As well as complete the KYC process.

With the implementation of Sub Accounts, users are able to create up to three - for now - Sub Accounts instantly and by themselves. With Sub Accounts there will be no need for users to go through account registration, complete KYC again or request support to link their accounts.

These new Sub Accounts cannot be logged in to and you cannot generate API keys for these accounts. All actions for these accounts are taken by the main account. This provides the benefit of not needing to log in to different accounts to perform actions. The main account can transfer funds both to and from these accounts.

To facilitate Sub Account actions, there are some new endpoints, as well as new parameter additions to existing endpoints. Below is a list of all HTTP API and WebSocket features:

Please note that if you encounter the message “Invalid use of subaccount API key” , it indicates that this endpoint is not applicable to the current sub-account.

WebSocket API:

• Private data feed subscription

HTTP API:

• Create sub account
• Get a list of sub accounts
• Get orders for a set of accounts
• Get executions for a set of accounts
• Place order for an account
• Amend order for an account
• Cancel order for an account
• Cancel all orders for set of accounts

Private Data Feed Subscription

Refer to this Link to get more information on using BitMEX WebSocket.

We have implemented new syntax for subscribing to multiple accounts via the websocket. When subscribing to a data feed, the syntax is:

{"op": "subscribe", "args": ["order"]}

This will subscribe to the authenticated account’s order feed. To subscribe to multiple account, you append the @[123, 456] tag to the end of the feed name, e.g:

{"op": "subscribe", "args": ["order@[123,456]"]}

This works for all feeds, if you have read permissions for those feeds. It also accepts a wildcard *, which subscribes to all accounts you have read access to, e.g:

{"op": "subscribe", "args": ["order@[*]"]}

Cancel All After works in the same way:

{"op": "cancelAllAfter", "args": 6000}

With accounts:

{"op": "cancelAllAfter", "args": "6000@[123,456]"}

Create Sub Account

With a new endpoint to create Sub Accounts, the Sub Account will be created immediately and linked to your main account.

Method: POST
Endpoint: https://www.bitmex.com/api/v1/user/addSubaccount\ Parameters:

• accountName: string, required. This is a reference value to identify your accounts by, it is not unique.

Returns:

{
  accountId: number,
  accountName: string
}

Get a List of Sub Accounts

The list of Sub Accounts exists on the user endpoint as new key “accounts”, it is an array of:

[{
  id: number,
  name: string, // either the account name, or the username if the role is LINKED_ACCOUNT
  role: "LINKED_ACCOUNT" or "SUB_ACCOUNT"
}]

If you have “Linked accounts”, you will see them in this list as well. The permissions on linked accounts are different to those of a Sub Account, which may have valid use cases, e.g. being able to isolate a Sub Account to a single API key. We have not migrated all linked accounts to the new Sub Accounts model.

To better understand what permissions each multi-account role type provides, there is another key mapping on the user called “authorizedAccounts”, this authorizedAccounts object returns the list of accountIds that the authenticated account has the permission for. The permissions are broken down based on the private data feed, as well as transfer permissions.

Method: GET
Endpoint: https://www.bitmex.com/api/v1/user\ Parameters: N/A
New Return keys:

{
  authorizedAccounts: [
    margin: {
      read: [number] //array of accountIds  
    },
    position: {
      read: [number] //array of accountIds  
    },
    execution: {
      read: [number] //array of accountIds  
    },
    order: {
      read: [number], //array of accountIds
      write: [number] //array of accountIds
    },
    transfer: {
      from: [number], //array of accountIds
      to: [number] //array of accountIds
    },
  ],
  accounts: [{
    id: number,
    name: string, // either the account name, or the username if the role is LINKED_ACCOUNT
    role: "LINKED_ACCOUNT" or "SUB_ACCOUNT"
  }]
}

Get Orders for a Set of Accounts

Method: GET
Endpoint: https://www.bitmex.com/api/v1/order\ Parameters:

• targetAccountIds: Array<number> | ["*"]. Not required, if not it will return the authenticated account’s orders. If it is an array of accountIds, it will return the orders for those accounts, If it is a wildcard (*), it will return orders for all of the accounts this authenticated account has order read permissions for.

Returns: Array<Order>

Get Executions for a Set of Accounts

Method: GET
Endpoint: https://www.bitmex.com/api/v1/execution\ Parameters:

• targetAccountIds: Array<number> | ["*"]. Not required. If not it will return the authenticated account’s orders. If it is an array of accountIds, it will return the executions for those accounts. If it is a wildcard (*), it will return executions for all of the accounts this authenticated account has execution read permissions for.

Returns: Array<Order>

Place Order for an Account

Method: POST
Endpoint: https://www.bitmex.com/api/v1/order\ Parameters:

• targetAccountId: number. Not required. If not added, will place an order on for the authenticated user. If it is there, and the user has order write permission for the targetAccount, then the order is placed for that account.

Returns: Order

Amend Order for an Account

Method: PUT
Endpoint: https://www.bitmex.com/api/v1/order\ Parameters:

• targetAccountId: number. Not required. If not added, will amend an order on for the authenticated user. If it is there, and the user has order write permission for the targetAccount, then the order is amended for that account.

Returns: Order

Cancel Order for an Account

Method: DELETE
Endpoint: https://www.bitmex.com/api/v1/order\ Parameters:

• targetAccountId: number. Not required. If not added, will delete an order on for the authenticated user. If it is there, and the user has order write permission for the targetAccount, then the order is deleted for that account.

Returns: Order

Cancel All Orders for a Set of Accounts

Method: DELETE
Endpoint: https://www.bitmex.com/api/v1/order/all\ Parameters:

• targetAccountIds: Array<number> | ["*"]. Not required, if not there will cancel the authenticated account’s orders, if it is an array of accountIds, it will cancel the orders for those accounts. If it is a wildcard (*), it will cancel orders for all of the accounts this authenticated account has order write permissions for.

Returns: Order