Position – TradrAPI Developer Docs

Positions

Positions are trades which are active on the market. The position is executed at the current market price.

Fetching Positions

To list positions the list() method under the positions namespace in the SDK should be used.

import { PaginatedResponse, Position } from '@tradrapi/trading-sdk';
 
const positions: PaginatedResponse<Position> = await tradrApi.positions.list({ accountId: 1 });

The list() method accepts a parameter of type ListPositionsDto which has the following interface:

interface ListPositionsDto {
  /**
   * The current page being returned.
   * @min 1
   * @default 1
   */
  page?: number;
  /**
   * Number of records per page.
   * @min 1
   * @default 10
   */
  limit?: number;
  /**
   * The sort direction of the records being returned
   * @default "DESC"
   */
  sortDir?: SortDir;
  /**
   * Filter the results by account id
   * @min 1
   */
  accountId?: number;
  /** Filter the results by position type */
  type?: PositionType;
  /** Filter the results by symbol */
  symbol?: string;
  /** Fetch only position created after, included ISO 8610 */
  from?: string;
  /** Fetch only position created before, included ISO 8610 */
  to?: string;
  /** Sort the results by the given property */
  sortBy?: PositionSortby;
}

The response of the list() method is a PaginatedResponse of type Position.

Position Model

interface Position {
  /** 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 ID of the position on the exchange */
  exchangeOperationId: string;
  /** The ID of the trade on the exchange which the position belongs to */
  exchangeTradeId?: string | null;
  /** The symbol name the position was placed on */
  symbol: string;
  /** The price at which the position was opened */
  openPrice: number;
  /** The take profit amount set on the position */
  takeProfit: number;
  /** The stop loss amount set on the position */
  stopLoss: number;
  /** The number of lots the position was placed for */
  lots: number;
  /** The contract size of the instrument the position belongs to */
  contractSize: number;
  /** The commission amount of the position */
  commission?: number;
  /** The commission amount of the position in USD */
  commissionUSD?: number;
  /** The swap amount of the position */
  swap?: number;
  /** The swap amount of the position in USD */
  swapUSD?: number;
  /** The comment present on the position */
  comment: string;
  /** The type of position */
  type: PositionType;
  /** The status of the position */
  status: PositionStatus;
  /** The IP address of the user who placed the position */
  ip?: string;
  /** The country of the user who placed the position */
  country?: string;
  /** The ID of the brand the position belongs to */
  brandId: number;
  /** The ID of the account the position belongs to */
  accountId: number;
  /** The ID of the group the position belongs to */
  groupId: number;
  /** The ID of the exchange the position belongs to */
  exchangeId: number;
  /** The ID of the exchange rate which is valid for the position */
  exchangeRateId?: number;
}

Opening A Position

To open a new position the open() method should be used

import { Position, PositionType } from '@tradrapi/trading-sdk';
 
const position: Position = await tradrApi.positions.open({
  accountId: 1,
  lots: 0.01,
  operation: PositionType.BUY,
  symbol: 'EURBTC',
});

This method accepts a parameter of type OpenPositionDto which has the following interface:

interface OpenPositionDto {
  /** The type of position */
  type: PositionType;
  /** The symbol to open the position for */
  symbol: string;
  /** The number of lots to open*/
  lots: number;
  /** A take profit amount to set on the position once it is opened */
  takeProfit?: number;
  /** A stop loss amount to set on the position once it is opened */
  stopLoss?: number;
  /** A comment for the position */
  comment?: string;
  /** The ID of the account to open the position for */
  accountId: number;
}

Closing A Position

To close an existing position the close() method should be used

import { ClosePositionResponseDto } from '@tradrapi/trading-sdk';
 
const response: ClosePositionResponseDto = await tradrApi.positions.close(1, { lots: 0.5 });

This method accepts a parameter of type ClosePositionDto which has the following interface:

interface ClosePositionDto {
  /** The number of lots to close. Leave empty to close the entire position */
  lots?: number;
  /** A comment to attach to the position, where applicable */
  comment?: string;
}

Since it is possible to close part of an existing position, the response of this method will return a ClosePositionResponseDto which has the following interface:

interface ClosePositionResponseDto {
  /** The ID of the position that was closed */
  exchangePositionId: string;
  /** The ID of the trade that was executed */
  exchangeTradeId?: string;
  /** The price at which the position was closed */
  closePrice?: number;
  /** The date/time the position was closed */
  closedAt?: string;
  /** The profit made on the position */
  profit?: number;
  /** The amount of open lots remaining in the position */
  lotsRemaining: number;
  /** Any new position which was opened as a result of the close */
  opened?: Position;
}

Closing All Positions

To close all existing positions the closeAll() method should be used

const result: boolean = tradrApi.positions.closeAll({ accountId: 1 });

The closeAllOpenOrders() method accepts a single parameter of type CloseAllTradesDto which has the following interface:

interface CloseAllTradesDto {
  /** The account ID for which to close all positions */
  accountId: number;
  /** Whether to also cancel any orders */
  incOrders?: boolean;
}

Updating An Existing Position

The update a position the update() method should be used:

import { Position } from '@tradrapi/trading-sdk';
 
const position: Position = await tradrApi.positions.update(1, {
  accountId: 101000123,
  stopLoss: 250.0,
});

The update method accepts a single parameter of type UpdatePositionDto which has the following interface:

interface UpdatePositionDto {
  /** A take profit amount to set on the position once it is opened */
  takeProfit?: number;
  /** A stop loss amount to set on the position once it is opened */
  stopLoss?: number;
}

Listing Historic Positions

To list historical positions the listHistoric() method under the positions namespace in the SDK should be used.

import { HistoricPosition, PaginatedResponse } from '@tradrapi/trading-sdk';
 
const historicPositions: PaginatedResponse<HistoricPosition> = await tradrApi.positions.listHistoric({ accountId: 1 });

The listHistoric() method accepts a parameter of type ListPositionsDto which is identical to the positions.list() method.

The response of the listHistoric() method is a PaginatedResponse of type HistoricPosition.

interface HistoricPosition {
  /** 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 type of the original position */
  type: PositionType;
  /** The status of the historic position */
  status: HistoricPositionStatus;
  /**
   * The date the position was opened
   * @format date-time
   */
  openedAt: string;
  /**
   * The date the historic position was closed
   * @format date-time
   */
  closedAt: string;
  /** The ID of the historic position on the exchange */
  exchangeOperationId: string;
  /** The ID of the trade on the exchange which the historic position belongs to */
  exchangeTradeId?: string;
  /** The symbol name the position was placed on */
  symbol: string;
  /** The price at which the position was opened */
  openPrice: number;
  /** The price at which the historic position was closed */
  closePrice: number;
  /** The take profit amount set on the position */
  takeProfit?: number;
  /** The stop loss amount set on the position */
  stopLoss?: number;
  /** The number of lots the position was placed for */
  lots: number;
  /** The contract size of the instrument the position belongs to */
  contractSize?: number;
  /** The commission amount of the historic position */
  commission?: number;
  /** The commission amount of the historic position in USD */
  commissionUSD?: number;
  /** The swap amount of the historic position */
  swap?: number;
  /** The swap amount of the historic position in USD */
  swapUSD?: number;
  /** The profit amount of the historic position */
  profit: number;
  /** The profit amount of the historic position in USD */
  profitUSD?: number;
  /** The comment present on the original position */
  comment?: string;
  /** The IP address of the user who placed the original position */
  ip?: string;
  /** The country of the user who placed the original position */
  country?: string;
  /** The ID of the brand the position belongs to */
  brandId: number;
  /** The ID of the account the historic position belongs to */
  accountId: number;
  /** The ID of the group the historic position belongs to */
  groupId: number;
  /** The ID of the exchange the historic position belongs to */
  exchangeId: number;
  /** The ID of the exchange rate which is valid for the historic position */
  exchangeRateId?: number;
}
 
enum HistoricPositionStatus {
  PARTIAL_CLOSE = 'PARTIAL_CLOSE',
  FULL_CLOSE = 'FULL_CLOSE',
  CANCELLED = 'CANCELLED',
}
 
enum PositionType {
  BUY = 'BUY',
  SELL = 'SELL',
}

Getting a single Historic Position

To get a single historical position the getHistoric() method under the positions namespace in the SDK should be used.

import { HistoricPosition } from '@tradrapi/trading-sdk';
 
const historicPosition: HistoricPosition = await tradrApi.positions.getHistoric(1);

The getHistoric() method accepts a single parameter of type number which is the ID of the historical position.

The response of the getHistoric() method is a HistoricPosition.

Order Migrating Accounts