What's New in cTrader Automate API 3.01

Spotware's avatar

Spotware since: 23 Sep 2013;

  23 Jul 2018, 15:11
What's New in cTrader Automate API 3.01

cTrader Automate (former cAlgo) implemented a new set of API in the version 3.01.
Using the new API you can configure the chart, where a cBot or an Indicator is running: get or set the chart settings, chart colors, scroll the chart positions, subscribe to the chart changes events, etc.
Also, we have added a new API to work with the objects that you can draw on the chart, like Trend Lines, Fibonacci Retracement, and others. Now you can draw all the chart objects available in cTrader, get existing objects from the chart and set their properties, receive events when the objects are added, removed, updated, hovered, or selected.

Here is the list of all the changes.

Chart Settings

  • Chart.DisplaySettings - contains settings for the items you see on the chart (Positions, Order, Grid, Deal map etc).
  • Chart.ColorSettings - contains the chart colors settings, like Candlesticks filling and background colors, etc.
  • Chart.Zoom - gets or sets the zoom level of the chart.
  • Chart.MarketSeries - access bar series used on the chart, like Open, High, Low, or Close.
  • Chart.TimeFrame - gets the timeframe of the chart.
  • Chart.Symbol - gets the symbol of the chart.
  • Chart.ChartType - gets the type of the chart (Bars, Candlesticks, Lines or Dots).
  • ChartArea.IsAlive - indicates if the indicator area is still on the chart.

Bars on the chart

  • Chart.BarsTotal - gets the number of the bars on the chart.
  • Chart.FirstVisibleBarIndex - gets the bar index of the first visible bar on the chart.
  • Chart.LastVisibleBarIndex - get the bar index of the last visible bar on the chart.
  • Chart.MaxVisibleBars - gets the maximum number of bars that can be shown on the chart with the current size and zoom level.

Size and scroll position

  • ChartArea.Width - gets the chart area width in pixels.
  • ChartArea.Height - gets the chart area height in pixels.
  • ChartArea.TopY - gets the highest value of the Y-axis in the visible area. For the main chart area, it is the top price that you see on the chart.
  • ChartArea.BottomY - gets the lowest value of the Y-axis in the visible area. For the main area, it is the lowest price you see on the chart.
  • Chart.ScrollXBy(int bars) - scrolls the chart for the specified number of bars to the right with a positive value, and to the left with a negative value.
  • Chart.ScrollXTo(int barIndex) - scrolls the chart to specified bar index, so that the first bar in the visible area will be the specified bar.
  • Chart.ScrollXTo(DateTime time) - scrolls the chart to the specified time, so that the specified time value will be in the time range of the first bar in the visible area.
  • ChartArea.SetYRange(double bottomY, double topY) - move or stretch the chart area upon the Y-axis.
  • Chart.IsScrollingEnabled - disable or enable the chart scrolling from the UI.

Chart events

  • Chart.DisplaySettingsChanged - occurs when one or multiple changes were made to the chart display settings.
  • Chart.ColorsChanged - occurs when one or multiple changes were made to chart color settings.
  • Chart.ChartTypeChanged - occurs when the type of the chart was changed.
  • Chart.ZoomChanged - occurs when the chart zoom level was changed.
  • Chart.IndicatorAreaAdded - occurs when an indicator was added to the chart that is drawn in its own chart area.
  • Chart.IndicatorAreaRemoved - occurs when an indicator was removed from the chart that is drawn in its own chart area.
  • ChartArea.SizeChanged - occurs when the size of the chart area was changed.
  • ChartArea.ScrollChanged - occurs when the first bar index or topY/bottomY has changed on the chart area.
  • ChartArea.MouseEnter - occurs when the mouse cursor enters the chart area.
  • ChartArea.MouseLeave - occurs when the mouse cursor leaves the chart area.
  • ChartArea.MouseMove - occurs when the mouse coordinates have changed in the chart area.
  • ChartArea.MouseDown - occurs when the left mouse button is pressed inside the chart area.
  • ChartArea.MouseUp - occurs when the left mouse button is released inside the chart area.
  • ChartArea.MouseWheel - occurs when the mouse wheel is scrolled.
  • ChartArea.DragStart - occurs when the chart area dragging was started using a mouse.
  • ChartArea.DragEnd - occurs when chart area dragging was stopped due to the left mouse button release or mouse capture was lost.
  • ChartArea.Drag - occurs when the mouse moves while the chart area is dragged.

Chart Objects

There are 14 chart objects available via the new cAlgo API:

  • ChartHorizontalLine
  • ChartVerticalLine
  • ChartTrendLine
  • ChartText
  • ChartStaticText
  • ChartIcon
  • ChartFibonacciRetracement
  • ChartFibonacciExpansion
  • ChartFibonacciFan
  • ChartAndrewsPitchfork
  • ChartEquidistantChannel
  • ChartRectangle
  • ChartEllipse
  • ChartTriangle

For each object, there is a corresponding method of drawing this particular object on a specific chart area.
Here is how to draw a horizontal line and make it interactive for a user:

var line = Chart.DrawHorizontalLine("my line", Symbol.Ask, Color.Red);
line.IsInteractive = true;

Calculate price of trend line

Now you can calculate a price value or indicator value of a trend line for a specific bar index or DateTime:

var line = Chart.DrawTrendLine("myLine", MarketSeries.OpenTime.Last(10), MarketSeries.High.Last(10), MarketSeries.OpenTime.LastValue, MarketSeries.High.LastValue, Color.Red);
line.ExtendToInfinity = true;
var price = line.CalculateY(MarketSeries.OpenTime.LastValue.AddHours(1));
Print("Next bar price is {0}", price);

Interactivity of ChartObject

The IsInteractive property has been introduced to the Chart objects. It allows creating interactive and non-interactive objects.
Non-interactive objects can't be changed by a user and are not visible by other cBots or Indicators. Only a cBot or an Indicator that owns non-interactive object can see it.
Interactive objects, on the other hand, can be seen and changed by a user or other cBots or Indicators that are working on the same chart.
When a cBot is stopped, or an Indicator is removed from the chart, all the non-interactive objects that belong to that cBot or Indicator will be removed from the chart automatically.

Chart API support in Optimization

Note that the Chart API is not supported in Optimization. If you call any methods from the Chart interface, the optimization will be stopped with the 'Not Supported' error.
If you plan to use a cBot or an Indicator in the Optimization, then you should avoid using the Chart interface in this mode. The mode can be checked using the new RunningMode property:

if (RunningMode != RunningMode.Optimization)

New Color class

The new Color class replaces the old Colors enumeration. Now you can specify the custom colors for indicators, chart objects, and chart color settings.
Color values can be set using RGB, ARGB, Hex string or using a color name.

Indicator line color

For the Indicator lines, we have implemented a new LineColor property in OutputAttribute. Before, only colors from the Colors enum were supported and the line color could be set like this:

[Output("Main", Color = Colors.Red)] 

The new LineColor property can be specified using the Hex value:

[Output("Main", LineColor = "#FF0000")] 

Or color name:

[Output("Main", LineColor = "Red")] 

Trading API shortcuts

For the Position and PendingOrders, we have added the shortcuts for modification and close/cancel methods. Now, most of the modification or close/cancel actions can be done by calling the methods directly on the Position and PendingOrder instance. Find the full list of the new methods below.

For Position:

  • Position.ModifyVolume
  • Position.ModifyStopLossPips
  • Position.ModifyStopLossPrice
  • Position.ModifyTakeProfitPips
  • Position.ModifyTakeProfitPrice
  • Position.ModifyTrailingStop
  • Position.Reverse
  • Position.Close

For PendingOrder:

  • PendingOrder.ModifyVolume
  • PendingOrder.ModifyExpirationTime
  • PendingOrder.ModifyTargetPrice
  • PendingOrder.ModifyStopLossPips
  • PendingOrder.ModifyTakeProfitPips
  • PendingOrder.ModifyStopLimitRange
  • PendingOrder.Cancel

Deprecated API

  • Colors enumeration (replaced with Color).
  • Color property for OutputAttribute (replaced with the LineColor property).
  • ChartObjects interface (replace with the ChartArea interface).
TRADERS FIRST™ Vote for your favorite features: https://ctrader.com/forum/suggestions
afhacker's avatar

afhacker since: 15 Oct 2015;

  23 Jul 2018, 16:39

Finally some real improvement!

Please add the platform time zone as a property in form of a TimeZoneInfo object so the developer will be able to know what's the user platform time zone setting, I don't know why you haven't added it yet.

ClickAlgo's avatar

ClickAlgo since: 05 Feb 2015;

  23 Jul 2018, 17:28

Thank you Spotware, this will allow vendors to create even more tools for the platform to help traders.

Do you have the API documented off-line in the form of a PDF document?

Paul Hayes
Sales & Marketing
Phone: (44) 203 289 6573

~ Contact us for all your cBot & Indicator development ~
ctrader.guru's avatar

ctrader.guru since: 19 Jul 2018;

  23 Jul 2018, 18:44

great work, thanks ...

Trade with us : https://ctrader.guru/pub/our-broker.php Follow our website : https://ctrader.guru/
Waxy's avatar

Waxy since: 12 May 2015;

  23 Jul 2018, 22:01

Hello Spotware,

This looks great and will help us develop better tools for trades.

I have two requests I haven't seen but been asking for it.

  1. Opacity for objects, this is important because chart data is sometimes blocked by these objects.
  2. Have an option to have objects drawn on backtests, but interactivity disabled.

Thanks for your continuous work.

¨You are not what you have done, you are what you have overcome.¨ - Anonymous
PanagiotisCharalampous's avatar

PanagiotisCharalampous since: 13 Jan 2017;

  26 Jul 2018, 09:50

Hi Waxy,

Transparency has already been added. We have a new Colors.FromArgb() function that allows you to set the alpha channel. Regarding interactivity, all chart objects have an IsInteractive property which is set to false by default.

Best Regards,


Head of Community Management at cTrader

Vitore since: 11 Feb 2018;

  27 Jul 2018, 12:00

A great improvements coming with v.3.00 and especially now with v3.01! It's been a long time of waiting for some of these recently introduced functionality and I'm very happy seeing them now available!

Please also focus on the mobile version now - the recent upgrade (though I understend the reasons behind) actually removed a lot of functionality and unlike on the desktop platform it represents a big move backwards (at least for me). Bring those functions back please and you're going to have a very powerful multi-platform system set

deanmikan@gmail.com since: 19 May 2018;

  29 Jul 2018, 04:33

Thank you so much devs!!!! This is the best update in a LONG time. I've been manually drawing rectangles for too long... And the visual mode looks and feels great.

Whilst I might have your attention, I would like to point out a massive bug in the backtest feature:
The ModifyPosition method is bugged in the fact that if you modify the volume to be less than that of the current position, it calculates the profit incorrectly. 

An example would be this code:

protected override void OnBar()
            if (Positions.Count == 0)
                ExecuteMarketOrder(TradeType.Sell, Symbol, Symbol.NormalizeVolumeInUnits(Account.Balance*5), "temp", 50, 50);
                if (Positions[0].NetProfit > 5)
                    ModifyPosition(Positions[0], Symbol.NormalizeVolumeInUnits(Positions[0].VolumeInUnits - 1000));


This will give you a profit in the billions of % due to it calculating every profit when modified as the original volume, despite only taking 1000 units in volume. Test on EURUSD for example.

Also it would be awesome if in future updates the devs could work on making the backtest feature less hell to use. When making over 2000 or 3000 trades the lag I experience, even ona a good computer, is atleast 20-30 wait times till I can even use the software without it not responding. And i'm quite sure there are many memory leaks in the software as using it for a long period of time it gets slower and slower.

Cheers Devs!

PanagiotisCharalampous's avatar

PanagiotisCharalampous since: 13 Jan 2017;

  30 Jul 2018, 09:42

Hi deanmikan@gmail.com,

Thanks for posting this issue. We will have a look at it and come back to you.

Best Regards,


Head of Community Management at cTrader
PanagiotisCharalampous's avatar

PanagiotisCharalampous since: 13 Jan 2017;

  23 Aug 2018, 15:04

Hi deanmikan@gmail.com,

We have released an update today that should have fixed this issue.

Best Regards,


Head of Community Management at cTrader