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 Global 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
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 cancelled
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?