General

The sub-account API can be used by an organisation to build a convenient interface for its employees to gain limited and controlled access to multiple trading accounts within one single master account.

This will improve the user experience for institutional and corporate clients who have many employees and need to test and manage numerous trading strategies simultaneously. Moreover, each sub-account will have its own set of API keys, giving users the flexibility to switch between sub-accounts instantly.

Terms and definitions

Super account (owner) — a regular user account, which is assigned to a list of several sub-accounts. To support sub-accounts, the super account must have 2FA enabled and be fully verified by successfully passing the KYC process. The super account is also referred to as the master account.

Sub-account — a regular user account (in Web, Core and Bank API), which has a link to a Super account and is managed by it as well.

Super accounts

SHOULD:

  • be verified, which implies:

    • enabled 2FA verification

    • successfully passed KYC process

CAN:

  • create a number of sub-accounts per Broker (the number of possible sub-accounts is subject to future alterations)

  • observe the sub-accounts trading activity and balances

  • control sub-accounts withdrawal ability (enable or disable)

  • freeze/unfreeze its sub-accounts (unfreeze does not mean enabling of withdrawals)

  • transfer funds between sub-accounts ignoring their freeze/unfreeze statuses

  • generate and manage API keys for its sub-accounts

  • have access to the list of its sub-accounts in a convenient way (via a single request).

CANNOT:

  • delete sub-accounts

  • manage sub-accounts without having a verified status itself

  • manage sub-accounts with disable status

Sub-accounts

SHOULD

  • inherit the following settings from the Super account:

    • security settings

    • AML limits

    • withdrawal fee

    • verification level (KYC)

    • user group

    • fees

  • inherit the super account's properties on update:

    • Verification level — sub-accounts, when created, inherit any verification level assigned to the Super account. When the verification level of the Super account changes, the verification level of a Sub account changes respectively. Verification levels are configured in the CRM

    • Withdrawal limits (AML) — withdrawal limits assigned to the Super account depend on the verification level. The total amount of all sub-accounts withdrawals cannot exceed the withdrawal limit of the Super account

    • Withdrawal Fee — is set up for the Super account by BEQUANT and is inherited by its sub-accounts (the fee level will be calculated based on the total transaction amount of the sub- accounts and corresponding Super account)

    • Trading fee tier — For sub-accounts a general trading fee tier is used (calculated based on the trading volume of all accounts). In case of any updates, the trading fee tier for the Super account changes in the same way as for the sub-account

  • have statuses, characteristic for Sub accounts only (active, invited ,frozen-invited, frozen)

  • have statuses, common for any account (new, active, disable)

  • have status disable on disabling (setting status to disable) the Super account

  • have its own 2FA secret key separate from the Super account's one (2FA is obligatory to perform withdrawals)

  • be represented as a regular account as well as a sub-account in the system.

CAN:

  • make deposits and withdrawals once KYC verification has been passed.

CANNOT:

  • have its own sub-accounts

  • transfer funds to another sub-account or the Super account via the Trading Account (funds must be transferred to the Main Account beforehand)

  • be registered using an email that exists in the database already (it must be a new email)

  • make withdrawals before setting 2FA secret

  • be active while the Super account is disabled.

State scheme for Sub-accounts

Screenshot_2020-04-26_at_14.07.18.png
  • active — account is fully functioning according to the parent account's preferences

  • invited — account is created, but not confirmed by email

  • frozen-invited — account is created, not confirmed, and frozen by the Super account

  • frozen — account is disabled, which implies the following:

    • withdrawals are disabled

    • trading is blocked

    • login is blocked

    • pending orders are canceled

    • API keys are disabled

Withdrawals statuses

  • enabled — payouts are enabled for Sub account

  • disabled — payouts are disabled for Sub account but still available for the Super account

API Specification (for Brokers)

Application error codes

500 = Internal Server Error
504 = Gateway Timeout
503 = Service Unavailable
1001 = Symbol not found
1002 = Authorisation required
2001 = Authorisation failed
10001 = Validation Error, Insufficient Funds

Get /sub-acc

Get a list of sub-accounts belonging to a Super account.

Request Body

No Parameters

Response Codes and Statuses

Code

Status

Description

200

success operation

sub-account list

Response Body

Name

Type

Description

id

integer

specifies the sub-account ID

Examples

Request

GET http://localhost:8083/api/2/sub-acc

Response (JSON)

[   {   "id": 123   }]

Post /sub-acc/freeze

Freeze specified sub-accounts (one or more).

Request Body

Name

Type

Description

Required

ids

string

specifies sub-account IDs separated by ","

True

Response Codes and Statuses

Code

Status

Description

200

success operation

success result

Response Body

No parameters

Examples

Request

POST http://localhost:8083/api/2/sub-acc/freeze[   {   "123",   "1234"   }]

Response (JSON)

[   {   "result": true   }]

Post /sub-acc/activate

Activate the specified frozen sub-accounts (one or more).

Request Body

Name

Type

Description

Required

ids

string

specifies sub-account IDs separated by ","

True

Response Codes and Statuses

Code

Status

Description

200

success operation

success result

Response Body

No parameters

Examples

Request

POST http://localhost:8083/api/2/sub-acc/activate[   {   "123",   "1234"   }]

Response (JSON)

[   {   "result": true   }]

Post /sub-acc/transfer

Transfer funds between super account and sub-account.

Request Body

Name

Type

Description

Required

fromAccountId

integer

specifies the userId of the source account

True

toAccountId

integer

specifies the userId of the target account

True

amount

string

specifies the amount of transferred funds

True

currency

string

specifies the currency of the transferred funds

True

Response Codes and Statuses

Code

Status

Description

200

success operation

Transaction ID

Response Body

No parameters

Examples

Request

POST http://localhost:8083/api/2/sub-acc/transfer[   {   "fromAccountId": "123",   "toAccountId": "1234",   "amount" : "100",   "currency": "ETH"   }]

Response (JSON)

[   {   "result": "955243"   }]

Get /sub-acc/acl

Check if withdrawals are enabled or disabled for a list of sub-accounts.

Request Body

Name

Type

Description

Required

subAccountIds

string

specifies sub-account IDs separated by ","

True

Response Codes and Statuses

Code

Status

Description

200

success operation

Sub-account ACL list

Response Body

Name

Type

Description

subAccountId

integer

specifies the Id of the sub-account

isWithdrawEnabled

boolean

specifies whether the withdrawal is enabled for the sub-account

description

string

specifies the description for the sub-account ACL

Examples

Request

GET http://localhost:8083/api/2/sub-acc/acl[   {   "subAccountIds": "123", "1234", ...   }]

Response (JSON)

[   {   "subAccountId": "123"   "isWithdrawEnabled": true,    "description": "123 sub-account description"   },   {   "subAccountId": "1234"   "isWithdrawEnabled": true,    "description": "1234 sub-account description"   }   ...]

Put /sub-acc/acl

Enable or disable withdrawals for a list of sub-accounts.

Request Body

Name

Type

Description

Required

subAccountIds

string

specifies sub-account IDs separated by ","

True

isWithdrawEnabled

boolean

specifies whether the withdrawal is enabled for the sub-account

False

description

string

specifies the description for the sub-account ACL

True

Response Codes and Statuses

Code

Status

Description

200

success operation

Sub-account ACL list

Response Body

Name

Type

Description

subAccountId

integer

specifies the Id of the sub-account

isWithdrawEnabled

boolean

specifies whether the withdrawal is enabled for the sub-account

description

string

specifies the description for the sub-account ACL

Examples

Request

PUT http://localhost:8083/api/2/sub-acc/acl[   {   "subAccountId": "123"   "isWithdrawEnabled": true,    "description": "123 sub-account description"   },   {   "subAccountId": "1234"   "isWithdrawEnabled": false,    "description": "1234 sub-account description"   }   ...]

Response (JSON)

[   {   "subAccountId": "123"   "isWithdrawEnabled": true,    "description": "123 sub-account description"   },   {   "subAccountId": "1234"   "isWithdrawEnabled": false,    "description": "1234 sub-account description"   }   ...]

Related articles: How to create Sub-Account?

Did this answer your question?