User Groups – TradrAPI Developer Docs

Group Management

Every account created in TradrAPI must belong to a group (sometimes also referred to as User Group). The group will determine many attributes of the account such as which symbols the account has access to view and trade as well as in certain cases the spreads and commissions the account will be charged.

Groups are assigned to an account upon registration using a rule based system. The rules are defined by the broker and can be based on any attribute of the account such as the country of residence, the account type, the account currency,

Listing Groups

In order to fetch a list of all groups, use the list() method under the group namespace under the admin namespace.

import { PaginatedResponse, Group } from '@tradrapi/trading-sdk';
 
const result: PaginatedResponse<Group> = await tradrApi.admin.group.list();

The list method accepts a single parameter which is an object of type ListGroupsRequest which allows filtering and pagination control:

interface ListGroupDto {
  /**
   * The current page being returned.
   * @default 1
   */
  page?: number;
  /**
   * Number of records per page.
   * @default 10
   */
  limit?: number;
  /**
   * The sort direction of the records being returned
   * @default "DESC"
   */
  sortDir?: SortDir;
  /** Filter by the group name */
  name?: string;
}

A single group may be fetched by passing the group id to the get() method:

import { Group } from '@tradrapi/trading-sdk';
 
const result: Group = await tradrApi.admin.group.get(212);

The response from either of the above methods will contain one of more Group models which are defined as follows:

interface Group {
  /** The TradrAPI ID of the entity */
  id: number;
  /**
   * The date the entity was created
   * @format date-time
   */
  createdAt: string;
  /**
   * The date the entity was last updated
   * @format date-time
   */
  updatedAt: string;
  /** The name of the group */
  name: string;
  /** The ID of the group on its relevant exchange */
  exchangeGroupId?: number;
  /** The brand which this group belongs to */
  brand?: Brand;
  /** The ID of the brand which this group belongs to */
  brandId: number;
  /** The exchange which this group belongs to */
  exchange?: Exchange;
  /** The ID of the exchange which this group belongs to */
  exchangeId: number;
  /** The server which this group belongs to */
  server?: Server;
  /** The ID of the server which this group belongs to */
  serverId: number;
}

Groups which have not yet been imported into TradrAPI but exist on the exchange may be queried using the following method:

import { UserGroupResult } from '@tradrapi/trading-sdk';
 
const result: UserGroupResult[] = await tradrApi.admin.group.listExchangeGroups();

The listExchangeGroups() method accepts a single optional parameter which is the brandUID by which to filter the results.

The response from the above method will contain one or more UserGroupResult models which are defined as follows:

interface UserGroupResult {
  /** The id of the group on the exchange (trading platform) */
  exchangeGroupId: string;
  /** The name of the group */
  name: string;
  /** The exchange which this group belongs to */
  exchange: Exchange;
}

Creating A New Group

⚠️

Creating a group via API does not automatically create the group on the exchange. Groups which are created on the exchange (trading platform) are automatically synced to TradrAPI (making the create() method redundant).

To create a new group in TradrAPI the following may be utilised:

import { Group } from '@tradrapi/trading-sdk';
 
const result: Group = await tradrApi.admin.group.create({
  name: 'My New Group',
  brandId: 1,
  exchangeUserGroupId: 1,
  serverId: 1,
});

The create() method accepts a single parameter which is an object of type CreateGroupDto which allows the

interface CreateGroupDto {
  /** The name of the group */
  name: string;
  /** The ID of the brand which this group belongs to */
  brandId: number;
  /** The ID of the group on its relevant exchange */
  exchangeUserGroupId?: number;
  /** The ID of the server which this group belongs to */
  serverId: number;
}

Updating An Existing Group

⚠️

Updating a group via the TradrAPI API does not update the the given group on the exchange. Updates made to groups on the exchange (trading platform) are automatically synced to TradrAPI, (making the update() method redundant).

To update an existing group in TradrAPI the following may be utilised:

const result: boolean = await tradrApi.admin.group.update(1, {
  name: 'My Updated Group Name',
});

The update() method accepts two parameters, the first being the ID of the group to update and the second being an object of type UpdateGroupDto which allows the following attributes to be updated:

interface UpdateGroupDto {
  /** The name of the group */
  name?: string;
  /** The ID of the group on its relevant exchange */
  exchangeGroupId?: number;
  /** The ID of the brand which this group belongs to */
  brandId?: number;
  /** The ID of the server which this group belongs to */
  serverId?: number;
}

Deleting A Group

Groups may be deleted using the delete() method and passing the TradrAPI groupId as the first parameter:

const result: boolean = await tradrApi.admin.group.delete(1);

Multiple groups may be deleted at once by passing an array of group IDs to the deleteMany() method:

const result: boolean = await tradrApi.admin.group.deleteMany([1, 2, 3]);

⚠️

Groups may only be deleted if they do not have any accounts assigned to them. If an attempt is made to delete a group which has accounts assigned to it, an error will be thrown.

⚠️

Deleting a group via the TradrAPI API does not delete the the given group on the exchange. Groups which are deleted on the exchange (trading platform) are automatically synced to TradrAPI.

User Group Aggregate Balances

Returns the aggregate balances of all accounts within a given group.

import { UserGroupAggregateBalance } from '@tradrapi/trading-sdk';
 
const result: UserGroupAggregateBalance[] = await tradrApi.admin.group.aggregateBalances(26732);

Response

An array of UserGroupAggregateBalance objects will be returned. Each object in the list contains the aggregate data grouped by a specific currency. If there are accounts within the group which have different currencies, then multiple objects will be returned in the list.

interface UserGroupAggregateBalance {
  /** The group id the aggregate balance belongs to */
  groupId: number;
  /** The group name the aggregate balance belongs to */
  groupName: string;
  /** The total sum of balances belonging to all accounts on this user group */
  balance: number;
  /** The total sum of equity belonging to all accounts on this user group */
  equity: number;
  /** The total sum of credit (bonus money) belonging to all accounts on this user group */
  credit?: number;
  /** The total sum of negative balances belonging to all accounts on this user group */
  negativeBalance?: number;
  /** The number of accounts within this user group which have a negative balance */
  numNegativeAccounts?: number;
  /** The currency of the aggregate */
  currency: string
  /** The date and time at which the aggregate data was recorded */
  recordedAt: string;
}

Spread Groups Adding a Project