SDKs
JavaScript/Typescript
User Methods
Accounts
Management

Account Management

Opening An Account

Every user level action that happens within TradrAPI needs to be associated with an account. A user can have multiple accounts, but each account can only be associated with one user.

Since TradrAPI supports a wide range of trading platforms, each with their own unique account requirements, we have created a standard account object that can be used to create an account on any platform.

The TradrAPI system can be configured on a project per project level to support the platforms that you need. The system is configured based on a set of criteria to route the creation of an account to the correct platform. These criteria are fully customizable and can be configured by the TradrAPI team to support any scenario.

If you need to register an account on a specific trading platform, then the open account request can directly specify the platform that the account should be created on. This will bypass the routing logic and create the account on the specified platform.

Example

import { AccountType, AccountResult, SupportedCurrency } from '@tradrapi/trading-sdk';
 
const account: AccountResult = await tradrApi.accounts.open({
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
  type: AccountType.Full,
  currency: SupportedCurrency.USD,
  leverage: 100,
});

The full request object CreateAccountDto is as follows:

interface CreateAccountDto {
  /** The type of account to create */
  type: AccountType;
  /** The leverage to create the account with */
  leverage: number;
  /** The currency the account will be created with */
  currency: SupportedCurrency;
  /** The first name of the account holder */
  firstName: string;
  /** The last name of the account holder */
  lastName: string;
  /** The email of the account holder */
  email: string;
  /** Only relevant to funded account challenged. Indicates the challenge stage the account is targeted to end up on. */
  stage?: string;
  /** Used to overwrite automatic group assignment. The name of the group to assign the account to (must exist). */
  groupName?: string;
  /** Used to overwrite automatic trading platform assignment. The name of the platform to create the account on (must exist). */
  exchange?: SupportedExchange;
  /** Used to overwrite automatic trading platform assignment. The version of the platform to create the account on (must exist). */
  exchangeVersion?: number;
  /**
   * The type of server to create the account on (Real/Demo funds).
   * @default "real"
   */
  server?: ServerType;
  /**
   * Account category type
   * @default "ecn"
   */
  category?: AccountCategoryType;
  /** A user-friendly name for the new account */
  friendlyName?: string;
  /** The master password to create the account with, if no password is specified a password will be generated where applicable */
  password?: string;
  /** A readonly access password to create the account with, if no password is specified a password will be generated where applicable */
  readonlyPassword?: string;
  /** A phone access password to create the account with, if no password is specified a password will be generated where applicable */
  phonePassword?: string;
  /** The lead source which generated the account */
  leadSource?: string;
  /** The gender of the account holder */
  gender?: AccountGender;
  /**
   * The language of the account holder
   * @default "en-us"
   */
  language?: AccountLanguage;
  /** The address of the account holder */
  address?: string;
  /** The zip code of the account holder */
  zipcode?: string;
  /** The city of the account holder */
  city?: string;
  /** The state of the account holder */
  state?: string;
  /** The country of residence of the account holder */
  country?: string;
  /** The phone number of the account holder */
  phone?: string;
  /** The comment to add to the account */
  comment?: string;
  /** Any data to associate with the account, in JSON format. */
  meta?: object;
  /** Whether the account should be marked as the user's favourite account */
  isFavourite?: boolean;
}

AccountResult Object

The AccountResult object returned from the open method (and other methods below) contains all the relevant information regarding the account that was created. An example of full object is as follows:

const example: AccountResult = {
  id: 100029715,
  createdAt: '2023-08-17T14:05:32.940Z',
  updatedAt: '2023-08-17T14:05:32.940Z',
  // the id of the user on the trading platform's server
  exchangeAccountId: '421247',
  // the id of the user on your project/application
  brandUserId: 'b09887ac-8905-4eed-b0be-774281036c50',
  // type of account
  type: 'hybrid',
  leverage: 100,
  userId: 29945,
  accountCurrency: 'USD',
  brandId: 9,
  groupId: 18,
  spreadGroupId: 452668,
  serverId: 4,
  meta: null,
  accountName: 'TRADEV#b09887ac-8905-4eed-b0be-774281036c50#1#1',
  isFavourite: false,
  serverType: 'real',
  group: {
    id: 18,
    createdAt: '2023-02-06T12:57:11.142Z',
    updatedAt: '2023-08-24T15:10:37.735Z',
    name: 'DEV-CUSTOM',
    exchangeGroupId: 2023,
    brandId: 9,
    exchangeId: 4,
    serverId: 4,
  },
  credentials: [
    {
      id: 52778,
      createdAt: '2023-08-17T14:05:32.910Z',
      updatedAt: '2023-08-17T14:05:32.910Z',
      /**
       * the type of credentials used
       * this determines the access the user logging in will have on the trading account
       * 'master' allows for full access
       */
      type: 'master',
      brandId: 9,
      serverId: 4,
      // the login used by the client, typically an email or a stringified integer, depending on the trading platform
      username: '[email protected]',
      // the password required to login
      password: 'fu2M4^X5',
      /**
       * The server public name, typically required to login to the respective trading platform
       * forward this value as is to the client, no server type appending is required.
       * it deprecates and replaces it.
       */
      serverPublicName: 'TRADEV-DEMO',
      /**
       * The exchange uid of the brand
       * deprecated Please use serverPublicName
       */
      server: 'TRADEV',
    },
  ],
  spreadGroup: {
    id: 452668,
    createdAt: '2023-07-25T09:31:13.158Z',
    updatedAt: '2023-08-24T15:10:54.253Z',
    name: 'DEV-NO',
    exchangeSpreadGroupId: 1105,
    exchangeId: 4,
    serverId: 5,
  },
  client: {
    id: 2,
    createdAt: '2023-03-02T14:43:46.372Z',
    updatedAt: '2023-03-02T14:43:46.372Z',
    serverId: 4,
    brandId: 9,
    links: [
      {
        value: 'https://stg.tradelocker.com/en/trade',
        platform: 'web',
        id: 1,
        createdAt: '2023-03-02T14:41:05.368Z',
        updatedAt: '2023-03-02T14:41:05.368Z',
      },
    ],
  },
  currency: {
    name: 'USD',
  },
  exchange: {
    id: 4,
    createdAt: '2023-02-06T10:02:50.472Z',
    updatedAt: '2023-05-09T15:12:01.423Z',
    name: 'TradeLocker',
    version: 1,
  },
};

Account Types

The following account types are supported by TradrAPI:

  • Limited although the account is created via TradrAPI, the account may not access the TradrAPI API and must interface with the trading platform directly.
  • Full the account is created via TradrAPI and can access the TradrAPI API. The account is not allowed to interface with the trading platform directly, no trading platform credentials are provided to the user.
  • Hybrid the account is created via TradrAPI and can access the TradrAPI API. The account is allowed to interface with the trading platform directly, trading platform credentials are provided to the user.

Considerations with TradeLocker

  1. TradeLocker forces each account created under the same username or email to share the same password. This behaviour is enforced by TradeLocker and is not configurable.

TradeLocker Account Flow

  1. TradeLocker limits the number of accounts a user may have to 100
  2. TradeLocker enforces the same email to be used if there is already and existing account under the same brandUserId with which the account is being created. This means that if you want to create multiple accounts for the same user, they must all share the same email.
import { AccountType, CreateAccountDto, SupportedCurrency } from '@tradrapi/trading-sdk';
 
const body: CreateAccountDto = {
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
  type: AccountType.Full,
  currency: SupportedCurrency.USD,
  leverage: 100,
};
 
const brandUserId = '507f1f77bcf86cd799439011';
const result1 = await tradrApi.accounts.open(body, brandUserId); // works fine
const result2 = await tradrApi.accounts.open(body, brandUserId); // works fine, user now has two TradeLocker users each one having one account
 
const newBrandUserId = '641d5f505e165c1c0d02a600';
const result3 = await tradrApi.accounts.open(body, newBrandUserId); // will fail due to the fact that TL internal validation.
  1. It's important that the Back office setup is done beforehand for your brand before creating accounts

Fetching An Account

Once an account has been created, it can be fetched using the get method under the accounts namespace in the SDK. The TradrAPI account ID is the unique identifier for an account.

import { AccountResult } from '@tradrapi/trading-sdk';
 
const account: AccountResult = await tradrApi.accounts.get('1010000201');

Alternatively you can fetch multiple accounts at once using the getMany method under the accounts namespace in the SDK.

import { AccountResult } from '@tradrapi/trading-sdk';
 
const accounts: AccountResult[] = await tradrApi.accounts.getMany(['1010000201', '1010000202']);
⚠️

All account ids must be accessible under whichever level of authentication is being used. For example, if you are using a user level token, then all account ids must be associated with the user that the token belongs to.

Listing Accounts

To list all accounts which belong to a single user you can use the list method under the accounts namespace in the SDK.

import { PaginatedResponse, AccountResult } from '@tradrapi/trading-sdk';
 
let brandUserId = '7c9c3a6e-539d-45e2-abb6-c91d7b9c8b46';
 
const accounts: PaginatedResponse<AccountResult> = await tradrApi.accounts.list(brandUserId);

For more info on pagination see the pagination section.

Updating An Existing Account

To update an existing account you can use the update method under the accounts namespace in the SDK.

const account: boolean = await tradrApi.accounts.update({
  accountId: 1010000201,
  firstName: 'John',
  lastName: 'Doe',
});

Please note that all properties except for the accountId are optional. The full request object UpdateAccountDto is as follows:

interface UpdateAccountDto {
  /** The account id to update */
  accountId: number;
  /** The first name of the account holder */
  firstName?: string;
  /** The last name of the account holder */
  lastName?: string;
  /** The email of the account holder */
  email?: string;
  /** The address of the account holder */
  address?: string;
  /** The zip code of the account holder */
  zipcode?: string;
  /** The city of the account holder */
  city?: string;
  /** The state of the account holder */
  state?: string;
  /** The country of residence of the account holder (ISO 3166) */
  country?: string;
  /** The phone number of the account holder */
  phone?: string;
  /** The leverage to create the account with */
  leverage?: number;
  /** Whether the account is allowed to open or close trades */
  isTradingAllowed?: boolean;
  /** Whether the account is suspended */
  isSuspended?: boolean;
  /**
   * The commission group the account belongs to
   * @example "MBD-GEN-USD"
   */
  commissionGroup?: string;
  /** Any data to associate with the account, in JSON format. */
  meta?: object;
}
GroupsPasswords