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.

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 not change from final back to transitional.

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. All orders should have a unique id.

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.

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.

note

Please note that our system identifies brackets as orders. Each new bracket should be returned with a unique id in /orders response when trying to attach brackets to the same parent order several times.

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 isTrailingStop and trailingStopPips parameters, even if the value of these parameters will be set to zero and false respectively.

Trailing Stop bracket placement and modification

When the user places or modifies a Trailing Stop bracket order, TradingView sends POST (PUT) /orders request with a trailingStopPips field in the payload (instead of sending a stopLoss field as it is done for a Stop Loss bracket order). Below is an example of the payload for the Buy Limit order placement with a Trailing Stop bracket for EURUSD forex pair:

currentAsk: 1.11162
currentBid: 1.11161
durationType: 2
instrument: EURUSD
limitPrice: 1.109
qty: 0.01
side: buy
trailingStopPips: 10
type: limit

The distance of the Trailing Stop bracket from the parent order price (or from the position price for a position Trailing Stop) is measured in pips. The specifics of pips calculation for different symbol types are described in the Pip value section.

TradingView system expects that the parameters of the Trailing Stop bracket placement request would be processed on partner's end, and a new or modified order would be returned in the next GET /orders response with the stopPrice, trailingStopPips and isTrailingStop parameters, which are the distinctive for the Trailing Stop bracket order. Below is an example of GET /orders response for the EURUSD forex pair:

{
    "id": "13542945SL",
    "instrument": "EURUSD",
    "qty": 0.01,
    "side": "sell",
    "type": "stop",
    "filledQty": 0.0,
    "avgPrice": 0.0,
    "stopPrice": 1.108000,
    "trailingStopPips": 10,
    "isTrailingStop": true,
    "parentId": "13542945",
    "parentType": "order",
    "duration": {
        "type": "2"
    },
    "lastModified": 1724407470,
    "status": "inactive"
}

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

Position is a result of an executed order. 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:

• All positions should have a unique id.
• 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.

Individual position - a position that is displayed on the chart despite the correlation of long and short positions. Net position - shows the difference between all of the user's long and short positions (i.e a total amount of currency for all open positions of the user).

Flag supportPositionNetting allows to show aggregated positions when multipositions are supported. With supportPositionNetting flag enabled instead of /positions two other endpoints will be requested:

• /individualPositions in response to this request we expect to receive all open positions. If user has 3 long and 2 short positions for a single instrument, we expect 5 positions in the response.
• /netPositions in response to this request we expect to receive aggregated positions. If user has 3 long and 2 short positions for a single instrument we expect one net position in the response.

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 sent as the amount property in the Close Position request.

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 sent in the Close Position request.

Please note, the enabled supportClosePosition flag does not disable the Close button. This flag affects the way the position is closed:

• If supportClosePosition flag is set to true - the DELETE Close Position request is sent.
• If supportClosePosition flag is set to false - the POST Place Order request with an opposite order is sent.

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.