Trading primitives

Overview

Trading primitives is a low-level mechanism that allows you to draw order, position, and execution lines directly on the chart.

This approach is fundamentally different from the standard Broker API integration. While the Broker API requires implementing a backend trading server to display real trading data, trading primitives act as specialized drawing tools. This allows creating visual elements without needing a full trading logic implementation.

caution

Starting from version 29, the methods for creating trading primitives are only available in Trading Platform.

Create trading primitive

You can create primitives using the following methods of the chart's API object (IChartWidgetApi).

• createOrderLine
• createPositionLine
• createExecutionShape

After the primitive is created, you can customize and interact with it using the API adapter. For example, the code sample below adds a new order line on the chart using the createOrderLine method.

const orderLine = await widget.activeChart().createOrderLine()

orderLine
    .setTooltip("Additional order information")
    .setModifyTooltip("Modify order")
    .setCancelTooltip("Cancel order")
    .setText("STOP: 73.5 (5,64%)")
    .setQuantity("2");

You can also attach callback functions to handle actions like modifying, canceling/closing, or moving/reversing lines. Inside a callback function, the this keyword refers to the API adapter of the primitive itself (e.g., IOrderLineAdapter). This allows you to call methods directly on the object in response to an event.

const orderLine = await widget.activeChart().createOrderLine();

orderLine
    .setQuantity("5")
    .setPrice(160)
    // Enables the "Cancel" button
    .onCancel(function() {
        console.log('Order cancelled. Removing line.');
        // Removes the line from the chart
        this.remove();
});

The callback registration methods (like onModify, onCancel) are overloaded. You can pass a single callback function, or you can pass a data object as the first argument and the callback as the second. This data object will then be passed to your callback.

// These are the static details of the order that your backend needs to identify it
const orderDetails = {
    avgPrice: 150,
    qty: 120,
};

// Create the order line on the chart
const orderLine = await widget.activeChart().createOrderLine();

orderLine
    .setQuantity("100")
    .setPrice(160)
    .setText("LIMIT BUY 100 @ 160.00")
    .onModify(orderDetails, function(data) {
        // 'this' refers to the orderLine object itself
        // 'data' is the orderDetails object we passed in

        // Set new price and quantity
        this.setPrice(data.avgPrice);
        this.setQuantity(data.qty);

        // Update the UI to give feedback to the user
        this.setText(`LIMIT BUY ${data.qty} @ ${data.avgPrice}`);
    });

Note that the buttons on an order or position line (e.g., Modify, Cancel, Close, Reverse) are displayed dynamically. If you do not provide a callback for a specific action, its button is hidden from the UI.

Customize appearance

You can set the default styles for order and position lines by using the trading_customization property in the Widget Constructor. For more information, refer to Customize trading primitives.

Styling reference

When customizing primitives, you can use the following formats for colors, fonts, and line styles:

Colors

• #RGB
• #RRGGBB
• rgb(red, green, blue)
• rgba(red, green, blue, alpha)

Fonts

You can use a string in the format: <bold> <italic> <size>pt <family>. For example, "bold 12px Verdana".

Line Styles

Style	Value
Solid	0
Dotted	1
Dashed	2