Skip to main content

Positions

Overview​

A position is the amount of a financial instrument held by an investor. A position is always a result of the executed order.

In the library, positions can be categorized into two types:

  • Regular positions. These are positions that are aggregated regardless of the position side, whether long or short. With regular positions, each symbol can have only one position. All user actions, such as buying or selling, result in either an increase or decrease in the position's quantity. For example, if a user buys 100 shares of a stock and later sells 50 shares, their position would be 50 shares.
  • Individual positions. These positions are displayed based on the position side, meaning that long and short positions are treated separately. Individual positions are used in the context of position netting, where all individual positions are aggregated to calculate a single net position for a particular symbol. For example, a user might have two individual positions for the same symbol: a long position of 100 shares and a short position of 50 shares. In this case, the net position would be 50 shares long.
tip

Before continuing with this article, we recommend reading Core concepts and Trading features configuration articles for a better understanding.

Handle and display regular positions​

When the chart is initially loaded, the library calls the positions method from your Broker API implementation. Your implementation should return an array of Position objects, containing data about the positions a user already held before the chart was created.

To update the library with any added or changed positions, your Broker API implementation should call the positionUpdate method on the Trading Host.

caution

You may encounter a timeout issue if the library fails to receive timely updates through positionUpdate.

User positions are displayed as follows:

  • On the chart, as a line based on the avgPrice value of the Position object.
  • On the Account Manager → Positions page. For more information, refer to the Orders and Positions section.

Handle multiple positions for one symbol​

The library supports two options for handling multiple positions for the same symbol: position netting and multiposition. Each option offers a different way of managing and displaying positions in the interface.

Position netting​

Position netting aggregates multiple individual positions for one symbol into a single net position. For example, a user might have two individual positions for the same symbol: a long position of 100 shares and a short position of 50 shares. In this case, the net position would be 50 shares long.

To enable position netting, use the supportPositionNetting flag. Once activated, this flag adds two new pages to the Account Manager within Positions: Individual Positions and Net Positions. Note that the number on the Positions tab represents only the total count of net positions.

Individual Positions and Net Positions pages in the Account Manager

Additionally, the library starts to operate with the following methods in the Broker API:

Your implementation should return arrays of IndividualPosition and Position objects, depending on the method the library calls. These objects should contain data about the positions a user already held before the chart was created.

To update the library with any added or changed individual/net positions, your Broker API implementation should call the individualPositionUpdate/positionUpdate methods on the Trading Host.

caution

You may encounter a timeout issue if the library fails to receive timely updates through individualPositionUpdate/positionUpdate.

Multiposition​

Alternatively, the multiposition option allows displaying multiple positions for the same symbol without aggregating them into a net position. To enable multiposition, set the supportMultiposition flag to true.

Unlike position netting, this flag does not affect how positions are calculated but affects how they are displayed in the interface. The library operates with the Broker API methods the same way as described in the Handle and display regular positions section.

Close positions​

The library supports two ways to close positions based on the value of the supportClosePosition/supportCloseIndividualPosition flag.

  • Default behavior (false) — positions are closed using market orders of the opposite side. The library calls the placeOrder method, passing the isClose property set to true in the PreOrder object.
  • Custom logic (true) — you can implement custom logic for closing positions. In this case, the library calls the closePosition/closeIndividualPosition method from the Broker API.
info

The library expects you to call the positionUpdate method whenever there is a new position added or existing one changed. This call is confirmation to the library that your backend server received and handled the request. Otherwise, the library will return a timeout issue.

Partial closing​

Partial position closing allows users to close part of a position while keeping the remainder open. When a user clicks the close button for a position, a dialog appears, allowing the user to specify the number of shares to close. For example, if the position size is 10, the user can choose any value between 1 and 10. The position is then updated to reflect the remaining number of shares.

To enable partial position closing, set the supportPartialClosePosition/supportPartialCloseIndividualPosition flag to true. The library then handles the closing based on the value of the supportClosePosition/supportCloseIndividualPosition flag:

Add brackets​

Bracket orders (brackets) are orders that protect positions. In other words, brackets help users limit their losses and secure their profits by bracketing positions with either one or two opposing stop-loss and take-profit orders. Refer to Bracket orders for more information.