Enrollments

Enrollments are entries in a challenge. They are created for or by a user and are used to track the user's progress in the challenge they belong to. A single trading account can only belong to a single enrollment in a challenge.

Getting An Enrollment

To get an enrollment, you can use the get method under the prop.enrollments namespace in the SDK. The method takes the ID of the enrollment as an argument and returns the enrollment object.

import { EnrollmentDto } from '@tradrapi/trading-sdk';
 
const enrollmentId: number = 289422032;
const enrollment: EnrollmentDto = await tradrApi.prop.enrollments.get(enrollmentId);

The response will be an EnrollmentDto object which has the following properties:

interface EnrollmentDto {
  /** The id of the enrollment */
  enrollmentId: number;
  /** The id of the challenge */
  challengeId: number;
  /** The id of the account */
  accountId?: number;
  /** The id of the account on the trading platform */
  platformAccountId: string;
  /** The type of enrollment */
  type: 'FREE_TRIAL' | 'STANDARD' | 'FUNDED' | 'INSTANT_FUNDED';
  /** The enrollment attributes */
  attributes: EnrollmentAttributesDto;
  /** The user enrolling */
  user: EnrollmentUserDto;
  /** The credentials of the enrollment */
  credentials: EnrollmentCredentialsDto;
  /** The status history of the enrollment */
  statusHistory: EnrollmentStatusHistoryDto[];
  /** The current enrollment stats */
  stats: EnrollmentStatsDto;
}
 
interface EnrollmentAttributesDto {
  /**
   * The date the enrollment starts at
   * @format date-time
   */
  startsAt: string;
  /**
   * The date the enrollment ends at
   * @format date-time
   */
  endsAt: string;
  /** The current status of the enrollment */
  status: 'IN_PROGRESS' | 'PASS' | 'FAIL' | 'RESET' | 'CANCEL' | 'FINISH';
  /** The type of challenge */
  challengeType: 'CHALLENGE' | 'COMPETITION';
  /** Represents the percentage of profit to be shared with the trader e.g. 70% */
  profitSharePercent: number;
  /** Represents the leverage for the account */
  leverage?: number;
  /** Represents whether weekend holdings apply */
  allowWeekendHoldings: boolean;
  /** Represents the leverage multiplier (factor) for the account (default 1) */
  leverageMultiplier: number;
  /** Represents whether a stop loss must be present on all trades */
  forceStopLoss: boolean;
  /** The number of days to extend the enrollment duration by (on top of the challenge default) */
  durationExtension: number;
  /** Represents the max allowed lots to be open at any one time */
  maxOpenLots?: number;
}
 
interface EnrollmentUserDto {
  /** The user's full name */
  fullName?: string;
  /** The user's email address */
  email?: string;
  /** An optional reference id to assign the enrollment */
  refId?: string;
}
 
interface EnrollmentCredentialsDto {
  /** The platform the account is on */
  platform: 'TL' | 'MT4' | 'MT5';
}
 
interface EnrollmentStatusHistoryDto {
  /** The current status of the enrollment */
  status: 'IN_PROGRESS' | 'PASS' | 'FAIL' | 'RESET' | 'CANCEL' | 'FINISH';
  /**
   * The datetime when the status was changed
   * @format date-time
   */
  updatedAt: string;
}
 
interface EnrollmentStatsDto {
  /** The current equity of the account */
  equity: number;
  /** The current balance of the account */
  balance: number;
  /** Represents the average loss amount across all losing trades */
  avgLoss: number;
  /** Represents the average profit amount across all winning trades */
  avgWin: number;
  /** Total profit amount / total loss amount */
  profitFactor?: number;
  /** The total number of lots traded */
  totalLots: number;
  /** The realised profit the account made */
  realizedProfitTotal: number;
  /** The unrealised profit the account has */
  unrealizedProfitTotal: number;
  /** The starting balance of the account */
  startingBalance: number;
  /** The starting balance of the account today */
  startingBalanceToday: number;
  /** The starting equity of the account today */
  startingEquityToday: number;
  /** The lowest equity the account has reached today */
  lowestEquityToday: number;
  /** The total number of days the account has traded */
  totalDaysTraded: number;
  /** The total number of trades opened */
  totalTradesOpened: number;
}

The stats property contains the trading statistics of the user in the challenge at the point in time when the enrollment was fetched.

Listing Enrollments

To list enrollments, you can use the list method under the prop.enrollments namespace in the SDK. The method takes an optional ListEnrollmentsDto object as an argument and returns a paginated list of enrollments.

import { EnrollmentDto, ResponsePaginated } from '@tradrapi/trading-sdk';
 
const enrollments: ResponsePaginated<EnrollmentDto> = await tradrApi.prop.enrollments.list({
  type: 'STANDARD',
  status: 'IN_PROGRESS',
  ...,
  page: 1,
  limit: 10,
});

The ListEnrollmentsDto object used in the above method has the following properties:

interface ListEnrollmentsDto {
  /** The enrollment ids to filter by */
  enrollmentIds?: number[];
  /** The challenge ids to filter by */
  challengeIds?: number[];
  /** The account ids to filter by */
  accountIds?: number[];
  /** The type of enrollments to filter by */
  types?: ('FREE_TRIAL' | 'STANDARD' | 'FUNDED' | 'INSTANT_FUNDED')[];
  /** The statuses to filter by */
  statuses?: ('IN_PROGRESS' | 'PASS' | 'FAIL' | 'RESET' | 'CANCEL' | 'FINISH')[];
  /** The challenge types to filter by */
  challengeTypes?: ('CHALLENGE' | 'COMPETITION')[];
  /** The stages to filter by */
  stages?: number[];
  /** The platforms to filter by */
  platforms?: ('TL' | 'MT4' | 'MT5')[];
  /**
   * The page number to return
   * @min 1
   * @default 1
   */
  page?: number;
  /**
   * The number of records to return
   * @min 1
   * @default 30
   */
  limit?: number;
}

Enrolling In A Challenge

To enroll in a challenge, you can use the create method under the prop.enrollments namespace in the SDK. The method takes an CreateEnrollmentDto object as an argument and returns the enrollment object.

import { EnrollmentDto } from '@tradrapi/trading-sdk';
 
const enrollment: EnrollmentDto = await tradrApi.prop.enrollments.create({
  challengeId: 1,
  accountId: 1,
  platformAccountId: '123456',
  ...
});

When enrolling into a challenge, it is possible to overwrite some of the challenge settings specifically for the new enrollment. Examples of such settings include the profit share percentage, the maximum drawdown percentage, the profit target percentage, and the maximum open lots, among others.

The CreateEnrollmentDto object has the following properties:

interface CreateEnrollmentDto {
  /** The id of the challenge */
  challengeId: number;
  /**
   * The id of the tradrapi account
   * @min 1
   */
  accountId: number;
  /** The id of the account on the trading platform */
  platformAccountId: string;
  /** The type of enrollment */
  type: 'FREE_TRIAL' | 'STANDARD' | 'FUNDED' | 'INSTANT_FUNDED';
  /** The email of the user enrolling */
  email?: string;
  /** The full name user enrolling */
  fullName?: string;
  /** The phone number of the user enrolling */
  phone?: string;
  /** An optional reference id to assign the enrollment */
  refId?: string;
  /**
   * The initial balance to allocate to the account
   * @min 1
   */
  initialBalance: number;
  /**
   * The leverage to create the account with
   * @min 1
   */
  leverage: number;
  /**
   * Overwrite the challenge value for this enrollment.
   * Whether weekend holdings apply.
   */
  allowWeekendHoldings?: boolean;
  /**
   * Whether a stop loss should be enforced on all trades made by this enrollment
   * @default false
   */
  forceStopLoss?: boolean;
  /**
   * The number of days to extend the enrollment duration by (on top of the challenge default)
   * @min 1
   * @max 365
   */
  durationExtension?: number;
  /**
   * Overwrite the challenge value for this enrollment.
   * Represents the percentage of profit to be shared with the trader e.g. 70%
   * @min 1
   * @max 100
   */
  profitSharePercent?: number;
  /**
   * Overwrite the challenge value for this enrollment.
   * The maximum total drawdown percentage allowed before failing
   * @min 1
   * @max 100
   */
  maxDrawdownPercent?: number;
  /**
   * Overwrite the challenge value for this enrollment.
   * The profit target to be reached before passing the challenge
   * @min 1
   * @max 500
   */
  profitTargetPercent?: number;
  /**
   * Overwrite the challenge value for this enrollment.
   * The max allowed lots to be open at any one time
   * @min 1
   */
  maxOpenLots?: number;
  /** Any comment to be attached to the enrollment */
  comment?: string;
}

The create method will return an EnrollmentDto object which represents the enrollment that was created.

Upgrading An Enrollment

An enrollment can be upgraded to a new enrollment of the same challenge with a different starting balance by using the upgrade method under the prop.enrollments namespace in the SDK.

When an enrollment is upgraded, the current enrollment is marked as UPGRADE and a new enrollment is created with the same settings as the current enrollment but with a new starting balance. The existing profit percentage from the old enrollment is carried over to the new enrollment.

The method takes the ID of the enrollment as an argument and returns the enrollment object once the upgrade is successful.

import { EnrollmentDto, UpgradeEnrollmentDto } from '@tradrapi/trading-sdk';
 
const enrollmentId: number = 289422032;
const enrollment: EnrollmentDto = await tradrApi.prop.enrollments.upgrade(enrollmentId, {
  accountId: 101003423,
  initialBalance: 100_000,
  reason: "Loyal customer"
});

A reason for the upgrade can be provided as an argument to the upgrade method.

export interface UpgradeEnrollmentDto {
  /**
   * The id of the new tradrapi account
   * @min 1
   */
  accountId: number;
  /**
   * The initial balance to allocate to the upgraded account
   * @min 1
   */
  initialBalance: number;
  /** The id of the upgraded account on the trading platform */
  platformAccountId: string;
}

ℹ️️

The enrollment must be in profit for it to be upgraded.

Converting A Free Trial Enrollment

A Free Trial enrollment can be converted to a Standard enrollment by using the convertFreeTrial method under the prop.enrollments namespace in the SDK. The method takes the ID of the enrollment as an argument and returns the enrollment object once the upgrade is successful.

import { EnrollmentDto } from '@tradrapi/trading-sdk';
 
const enrollmentId: number = 289422032;
const enrollment: EnrollmentDto = await tradrApi.prop.enrollments.convertFreeTrial(enrollmentId, { reason: "Loyal customer" });

A reason for the free trial conversion can be provided as an argument to the convertFreeTrial method.

export interface ConvertTrialEnrollmentDto {
  /** Any comment to apply to the enrollment conversion */
  comment?: string;
}

ℹ️️

Only Free Trial type enrollments can be converted.

Updating An Enrollment

An enrollment can be updated enrollment by using the update method under the prop.enrollments namespace in the SDK. The method takes the ID of the enrollment as an argument allows for certain properties of the enrollment to be updated.

const enrollmentId: number = 289422032;
const success: Boolean = await tradrApi.prop.enrollments.update(enrollmentId, { maxPayoutInterval: 8 });

export interface UpdateEnrollmentDto {
  /**
   * Represents the maximum payout interval in hours for the enrollment
   * @min 1
   */
  maxPayoutInterval?: number;
}

Passing An Enrollment

An enrollment can be forcefully passed by using the pass method under the prop.enrollments namespace in the SDK. The method takes the ID of the enrollment as an argument and returns a boolean indicating whether the process was successful.

const enrollmentId: number = 289422032;
const isPassed = await tradrApi.prop.enrollments.pass(enrollmentId, { reason: "Cheater" });

A reason can be optionally provided as an argument to the pass method.

interface PassEnrollmentDto {
  /** Any comment to apply to the enrollment */
  reason?: string;
}

Cancelling An Enrollment

An enrollment can be forcefully cancelled by using the cancel method under the prop.enrollments namespace in the SDK. The method takes the ID of the enrollment as an argument and returns a boolean indicating whether the cancellation process was successful.

const enrollmentId: number = 289422032;
const isCancelled = await tradrApi.prop.enrollments.cancel(enrollmentId, { reason: "On customer request" });

The reason for the cancellation can be optionally provided as an argument to the cancel method.

interface CancelEnrollmentDto {
  /** Any comment to apply to the enrollment cancellation */
  reason?: string;
}

Once an enrollment is cancelled, it is considered as failed and the user will not be able to trade on the account

Resetting An Enrollment

An enrollment can be reset by using the reset method under the prop.enrollments namespace in the SDK. Resetting an enrollment cancel the current enrollment and create a new one with the same settings.

The method takes the ID of the enrollment as an argument and returns the new enrollment object once the reset is successful.

import { EnrollmentDto } from '@tradrapi/trading-sdk';
 
const enrollmentId: number = 289422032;
const enrollment: EnrollmentDto = await tradrApi.prop.enrollments.reset(enrollmentId,
  { accountId: 101003423, platformAccountId: '3022932' }
);

The reset method requires that the Ids of the new TradrAPI account and platform account are provided in the ResetEnrollmentDto object.

interface ResetEnrollmentDto {
  /**
   * The id of the tradrapi account
   * @min 1
   */
  accountId: number;
  /** The id of the account on the trading platform */
  platformAccountId: string;
}

ℹ️️

Only In Progress enrollments can be reset.

Challenges Servers