Skip to main content

Concepts

Orders and order history​

Orders​

Orders are instructions to a broker to purchase or sell assets on a user’s behalf. On the TradingView platform, the Orders tab displays all orders received in response to /orders.

Orders tab

When an order is placed, it follows a process of order execution. In the order execution process, orders have statuses that can be divided into two groups:

  • Transitional

    • Placing — an order is registered by the broker, but the exchange has not confirmed the status yet.
    • Working — an order is created and approved by the exchange but not executed yet.
    • Inactive — an order is in the system, but not at work.

  • Final

    • Filled — an order is successfully executed.
    • Canceled — an order is canceled by a user.
    • Rejected — an order is rejected for some reason, for example, the exchange rejected the order.
info

The order status can only change from transitional to final, not vice versa.

The /orders endpoint is used to get all orders of the current trading session and orders with transitional statuses from previous sessions (otherwise, the user will not see that there is a pending order). Orders that have received the final status should be included in the list before the end of the session, or at least within one minute after the change in the order status.

Order history​

The /ordersHistory endpoint is used to get order history for the account. On the TradingView platform, the History tab displays all orders received in response to the /ordersHistory request and orders with the final status received from /orders. Orders with final statuses from /orders are simultaneously displayed on both the Orders and the History tabs.

Here is entire flow.

  1. User is login to the integration.
  2. /orders is requested for the first time and /ordersHistory is requested just once.
  3. Two tables for Orders and History tabs are built based on the responses.
  4. The Orders tab contains all orders from /orders regardless of their status.
  5. The History tab contains orders only with final status (filled, canceled or rejected) from /ordersHistory and orders with final status from /orders.

Further /orders keep being requested. If the next response contains the information that any order has moved from the transitional status (placing, working or inactive) to the final status, that order will remain in the Orders tab with the final status and will be duplicated to the History tab. The order will still be displayed in both tabs even if it is no longer sent to /orders after that. This will be the case until the next login or page refresh. After the next login or page refresh the first /orders request and one-time /ordersHistory request will be made again and the history of the orders will start accumulating from the beginning.

Orders history

Brackets​

By brackets in our UI we mean orders, the meaning of which is to protect the position. Brackets always have the opposite side to the order or position compared to its parent. The quantity in bracket orders is always equal to the quantity of their parent order.

Brackets can exist either in a pair (Stop-Loss and Take-Profit) or separately. This means that the order or position can have only one bracket order (Stop-Loss or Take-Profit).

If a pair exists, bracket orders are linked by an OCO (One-Cancels-the-Other) condition. It means that when one bracket order is executed, the other (if any) is automatically cancelled. When one of the brackets is partially executed, the quantity in the second bracket order should be automatically reduced to the remaining quantity of the partially executed bracket order on the broker's side.

Order brackets​

The supportOrderBrackets flag in the /accounts must be set to true to support order brackets in our UI. In this case, sections for bracket orders will appear when switching to the order editing mode.

Placing a parent order with brackets​

When placing an order with brackets through our UI, a POST request is sent to the broker's server with stopLoss and takeProfit fields or one of them. If the parent order has not been executed immediately, then we expect the parent order to appear in working status, and one or two (depending on the presence of fields stopLoss and takeProfit) in inactive status in the next response to the /orders request.

It is necessary for bracket orders in /orders to have a parentId field, the value of which is the id of their parent order. The parentType field of bracket orders has the order value.

Modifying parent order with brackets, adding, or removing brackets​

The result of editing the order in our UI is a PUT request to the broker's server with new order parameters, including stopLoss and takeProfit fields, or one of them.

If the user has deleted one of the brackets when changing the parent order, then it is necessary to send a removed bracket order with cancelled status in subsequent responses to the /orders request. Otherwise, an error will come up: this bracket will "hang" in our user interface in the table of orders and on the chart.

The cancellation of one of the brackets should not lead to the cancellation of another bracket order and the parent order.

Execution of a parent order with brackets​

Bracket orders are bound to the parent order by the OSO (One-Send-Other) condition. When a parent order is executed, bracket orders are transferred to the working status.

If bracket positions are supported, the parentId field of the brackets gets the id value of the position that resulted from the parent order execution, and the parentType field of the bracket orders changes its value to position.

Canceling a parent order with brackets​

Bracket orders are bound to the parent order by the OSO condition. Therefore, when cancelling a parent order, the brackets must also be cancelled.

Trailing stop bracket​

In order to support placing Trailing Stop brackets the supportTrailingStop in the /accounts must be set to true. When this parameter is enabled, it will be possible to change Stop Loss bracket to Trailing Stop by clicking on the bracket's name in the UI.

info

No other order besides Trailing Stop should contain trailingStopPips parameter, even if the value of this parameter will be set to zero.

Guaranteed stop bracket​​

In order to support placing Guaranteed Stop brackets the supportGuaranteedStop flag in the /accounts must be set to true. When this parameter is enabled, it will be possible to change Stop Loss bracket to Guaranteed Stop by clicking on the bracket's name in the UI.

Position brackets​

The UI behavior differs depending on whether the broker supports bracket position or not. To support position brackets, the supportPositionBrackets flag in the /accounts must be set to true. So, when the user switches to edit mode, sections for bracket orders will appear.

Support of position brackets vary if a broker does not have support for multiple positions at one instrument at the same time. Multiple position means that each trade opens its own separate position, to which you can add brackets and which can only be closed completely. If you support multi position set the supportMultiposition flag to true.

Position brackets are not supported​

In this case, after the parent order is executed, the brackets don't receive the position id to the parentId field and are no longer linked to the parent order. But the OSO brackets binding between each other must be kept on the broker's side. When a position is closed, all orders in the transit statuses (placing, inactive, working) are usually canceled.

Position brackets are supported​

When one of the bracket orders is executed, the position is reset to zero, and the other bracket order (if any) is transferred to the cancelled status. When one of the bracket orders is partially executed, the quantity in the position is reduced by the executed quantity. The quantity in the other bracket order is given according to the left quantity in the partially executed bracket order.

When the user adds brackets to the position, the broker's server receives a PUT request Modify Position, which contains stopLoss and takeProfit fields, or one of them.

Then these bracket orders return with working status to /orders with next values:

  • parentId — the value of the position id field,
  • parentType — the value of the position field,
  • qty — the number of units.

When the user closes position, the brackets should be cancelled and sent to /orders with the cancelled status.

tip
  1. Open a position using a market order with Take-Profit and Stop-Loss.
  2. Got a position with brackets (Take-Profit and Stop-Loss).
  3. Close the position.
  4. Brackets are canceled too.

Positions​

There are two types of positions:

  • Long position is formed as a result of buying a symbol.
  • Short position is formed as a result of selling a symbol.

You can display Positions in the Account Manager and on the Chart.

There are several details about positions that you need to consider:

  • There are no positions for Crypto Spots, but they are present for Crypto Derivatives.
  • Available operations for the positions include Protect Position, Reverse Position, and Close Position. Use flags in the /accounts → d → config to hide or enable the operations.
  • You can use multidirectional positions for those instruments that support this feature, e.g., for crypto derivatives and Forex. To do this, set supportMultiposition: true in the /accounts endpoint.

Close position​

Users can close their positions in three ways:

  • Via the Chart.
  • Via the DOM panel.
  • Via the Account manager panel, by right-clicking the position and selecting Close Position.

If you want users to be able to close their positions partially, set supportPartialClosePosition: true in the /accounts endpoint. In the Close position pop-up window, an additional Partial close option appears, and users can specify the number of units to close. In this case, the specified number is returned as the amount property in the Close Position endpoint.

Close Position Partially

info

Users won't be able to partially close the position if they enable the Instant orders placement option in the Chart settings → Trading section. Also in this case, the amount property is not returned in the Close Position endpoint.

Reverse position​

Users can reverse positions from long to short or from short to long in three ways:

  • Via the Chart.
  • Via the DOM panel, by clicking the Reverse button.
  • Via the Account manager panel, by right-clicking the position and selecting Reverse Position.
note

If you want to hide the Reverse Position option, set supportReversePosition: false in the /accounts endpoint.

Also, you can make the integration natively support the position reverse. To do this, set supportNativeReversePosition: true in the /accounts endpoint. In this case, TradingView sends requests to the Modify Position endpoint with the side parameter set.

If supportNativeReversePosition: false, TradingView sends a market order with a double quantity and the opposite side of the position via the Place Order endpoint.

Profit and loss values​

Profit & loss (P&L) values indicate the current profit or loss status of an account or position. The P&L values for accounts are displayed in the Account Summary row. They should be returned in the unrealizedPL field of the /state endpoint.

The P&L values for positions are displayed on the chart and the Positions tab. TradingView can automatically calculate the P&L values for positions. In this case, you should set supportPLUpdate: false in the /accounts endpoint.

However, TradingView recommends using your own P&L calculations for positions. This helps avoid any discrepancies between the P&L values of the account and positions due to potential delays. To use your calculations, set supportPLUpdate: true in /accounts. The P&L value should be returned in the unrealizedPL field of the /positions endpoint.

Pip value​

The main purpose of pipValue is to calculate risks in an Order Ticket (for those who use it). This parameter's value is specified in the account currency.

pipValue is a cost of pipSize in the account currency. So, pipValue = pipSize when account currency and instrument currency match. pipSize = minTick for all instruments, except currency pairs. For Forex pairs it equals either the minTick or the minTick multiplied by 10. For Forex instruments, the pipValue size depends on the rapidly changing currency cross rates. You should always send the actual value.

Besides /instruments, pipValue can be sent via /quotes in the buyPipValue and sellPipValue fields. However, if you do not have support for different pipValue for buy and sell, you should pass the same values in both fields.

By default we use pipValue parameter to display profit/loss. If you provide unrealizedPl parameter in /positions, you should set supportPLUpdate flag in /accounts to true. But the profit is fixed when the position is closed:

  • at Bid — when Short position closed,
  • at Ask — when Long position closed.

Quotes​

Quotes are the current prices of the instrument - bid/ask. If the hasQuotes flag in /instruments endpoint is set to false, the bid/ask values from the TradingView's backend (if availbale) are used. If the hasQuotes flag in /instruments endpoint is set to true, the bid/ask values are taken from the response of the /quotes endpoint. Note that this is only applied to the buy/sell buttons when logged into the broker.

info

Quotes on the chart from the datafeed are updated slower than the quotes coming from the /quotes response. This can lead to the execution of orders at unexpected prices, hence, the /quotes endpoint is mandatory.