Routing Rules – TradrAPI Developer Docs

Account Routing Rules

Rules are used to determine, at the point of account registration, the trading platform (also referred to as exchange) onto which to place the account and the user group within that trading platform to which the account should be assigned.

Rules are defined on a project-per-project basis and then used automatically by the account registration process in TradrAPI.

⚠️

It is possible to bypass the rules by specifying the trading platform and user group directly in the account registration request.

Creating A New Rule

In order to create a new account rule, the add() method under the admin.rule namespace should be utilised.

import { RuleDto } from '@tradrapi/trading-sdk';
 
const result: RuleDto = await tradrApi.admin.rule.add({
  comment: 'This is a new rule',
  type: 'account-routing',
  rule: {...}
});

The add() method accepts a single parameter of type CreateRuleDto which is defined as follows:

interface CreateRuleDto {
  /** Any comment related to the new rule being created */
  comment?: string;
  /** The rule to be created */
  rule: Rule;
  /** The type of rule to be created */
  type: 'account-routing' | 'tl-risk-plan';
}

The Rule interface is defined as follows:

type ConditionType = "any" | "all" | "none";
type Operator =
  | "=="
  | "!="
  | ">"
  | "<"
  | ">="
  | "<="
  | "in"
  | "not in"
  | "contains"
  | "not contains"
  | "contains any"
  | "not contains any"
  | "matches"
  | "not matches";
 
interface Constraint {
  field: string;
  operator: Operator;
  value:
    | string
    | number
    | boolean
    | Record<string, unknown>
    | (string | number | boolean | Record<string, unknown>)[];
}
 
interface Condition<R = any> {
  any?: (Constraint | Condition<R>)[];
  all?: (Constraint | Condition<R>)[];
  none?: (Constraint | Condition<R>)[];
  result?: R;
}
 
interface Rule<R = any> {
  conditions: Condition<R> | Condition<R>[];
  default?: R;
}

Fetching One Or More Rules

Existing rules can be fetched using the get() or list() methods under the admin.rule namespace.

import { RuleDto } from '@tradrapi/trading-sdk';
 
const ruleId = 123;
const result: RuleDto = await tradrApi.admin.rule.get(ruleId);

or to fetch all rules:

import { RuleDto, PaginatedDto, PaginatedResponse } from '@tradrapi/trading-sdk';
 
const result: PaginatedResponse<RuleDto> = await tradrApi.admin.rule.list({
  limit: 10,
  page: 1
});

Updating Rules

In order to update an existing rule, the update() method under the admin.rule namespace should be utilised.

const ruleId = 123;
const result: boolean = await tradrApi.admin.rule.update(ruleId, {
  comment: 'This is an updated rule',
  ruule: {...}
});

The update() method accepts a single parameter of type UpdateRuleDto which is defined as follows:

interface UpdateRuleDto {
  /** Any comment related to the new rule being created */
  comment?: string;
  /** The rule to be updated */
  rule: Rule;
}

Deleting A Rule

In order to delete an existing rule, the delete() method under the admin.rule namespace should be utilised.

const ruleId = 123;
const result: boolean = await tradrApi.admin.rule.delete(ruleId);

The delete() method accepts a single parameter of type number which is the ID of the rule to delete.

Evaluating A Rule

To evaluate a rule (test it), the evaluate() method under the admin.rule namespace should be utilised. This allows you to test a rule against a given set of constraints.

const ruleId = 123;
const result: number = await tradrApi.admin.rule.evaluate<number>(ruleId, {...});

The evaluate() method accepts a criteria object of type Record<string, unknown> which is used to test the rule against.

Rule Dimensions

Rules dimensions are used to define the allowed condition fields and their respective operators for the rules you create.

Every rule must have at least one dimension defined. By default, some dimensions are already available for use. These dimensions are not editable and cannot be deleted but can be used in any rules you create.

These predefined dimensions are:

category
leverage
currency
platform
monetization

Creating A New Dimension

In order to create a new rule dimension, the addDimension() method under the admin.rule namespace should be utilised.

import { RuleDimensionDto } from '@tradrapi/trading-sdk';
 
const result: RuleDimensionDto = await tradrApi.admin.rule.addDimension({
  dimension: 'PromoCode',
  type: 'text'
});

When adding a new dimension, the addDimension() method accepts a parameter of type CreateRuleDimensionDto which is defined as follows:

interface CreateRuleDimensionDto {
  /** The dimension name */
  dimension: string;
  /** The type of the dimension to be created */
  type: 'text' | 'numeric' | 'boolean' | 'list' | 'numeric_list';
  /** The dimension's allowed values */
  values?: object[];
}

Fetching Dimensions

Existing dimensions can be fetched using the getDimension() or listDimensions() methods under the admin.rule namespace.

import { RuleDimensionDto } from '@tradrapi/trading-sdk';
 
const dimensionId = 123;
const result: RuleDimensionDto = await tradrApi.admin.rule.getDimension(dimensionId);

or to fetch all dimensions:

import { RuleDimensionDto, PaginatedDto, PaginatedResponse } from '@tradrapi/trading-sdk';
 
const result: PaginatedResponse<RuleDimensionDto> = await tradrApi.admin.rule.listDimensions({
  limit: 10,
  page: 1
});

Updating Dimensions

In order to update an existing dimension, the updateDimension() method under the admin.rule namespace should be utilised.

In this example we are restricting the possible input values for the PromoCode dimension to promo1 and promo2.

const dimensionId = 123;
const result: boolean = await tradrApi.admin.rule.updateDimension(dimensionId, {
  dimension: 'PromoCode',
  type: 'text',
  values: ['promo1', 'promo2']
});

Deleting Dimensions

In order to delete an existing dimension, the deleteDimension() method under the admin.rule namespace should be utilised.

const dimensionId = 123;
const result: boolean = await tradrApi.admin.rule.deleteDimension(dimensionId);

The deleteDimension() method accepts a single parameter of type number which is the ID of the dimension to delete.

Introspection

The introspect() method under the admin.rule namespace should be utilised to introspect a rule. This allows you to ask the API for the possible range of inputs which would be provided to a rule, given a criteria object which you also provide.

Essentially, you can ask the API, "If I were to evaluate this rule with { "leverage": 100 }, what would the possible values for currencies be that would satisfy the rule?"

To do this, you would call the introspect() method as follows:

const ruleId = 123;
const result: Record<string, unknown> = await tradrApi.admin.rule.introspect(ruleId, {
  dimensionId: 1,
  subjectIds: [2,3],
  value: 100
});

Here, we ask the API to introspect the rule with ID 123 and to provide us with the possible values for the dimensions defined as subjectIds, if part of the input criteria object is the dimension with id 1 and having a value of 100.

The introspect() method accepts a parameter of type IntrospectRuleDto which is defined as follows:

interface IntrospectRuleDto {
  /** The dimension id which we are introspecting */
  dimensionId: number;
  /** The dimension ids to introspect against */
  subjectIds: number[];
  /** The value to assign to the dimension being introspected */
  value: string;
}

The introspect() method returns a IntrospectionResultDto object which contains the possible values for the dimensions being introspected (subjectIds).

interface IntrospectionResultSubjectDto {
  /** The id of the dimension */
  dimensionId: number;
  /** The name of the dimension */
  name: string;
  /** The list of possible values for the dimension which would satisfy the rule */
  values: IntrospectionResultSubjectValues[];
}
 
interface IntrospectionResultSubjectValues {
  /** The operator to apply to the value */
  operator: object;
  /** The value of the dimension */
  value: object;
}
 
interface IntrospectionResultDto {
  /** The id of the dimension */
  dimensionId: number;
  /** The name of the dimension */
  name: string;
  /** The requested subjects which are allowed */
  subjects: IntrospectionResultSubjectDto[];
  /** The value of the dimension */
  value: object;
}

Overview Update Balances