Advanced cBot Operations¶

Introduction¶

This guide is primarily intended as a complement to our extensive list of cBot code samples.

Trading Other Symbols¶

You can develop a cBot that trades multiple symbols in addition to the one specified when creating a new instance.

Making it possible, Symbols is a collection of all symbols available to your trading account. You can iterate over it by using loops; alternatively, you can search over it to find specific symbols.

To correctly work with multiple symbols, cBots need to know the following information.

The minimum/maximum allowed volume.
The volume step.
The pip tick size.
The pip tick value (the monetary value of one pip/tick in the account deposit currency).

This data can be learned from a Symbol object instance. In the below code, we find a symbol with "GBPUSD" as its name and then create a market order for it. We also use its minimum allowed volume as order volume.

  [Robot()]
  public class Sample_cBot : Robot
  {
      protected override void OnStart()
      {
          var symbol = Symbols.GetSymbol("GBPUSD");

          if (symbol is not null)
          {
              _ = ExecuteMarketOrder(TradeType.Sell, symbol.Name, symbol.VolumeInUnitsMin);
          }
      }
  }

In the example above, the underscore represents a discarded variable. We are not interested in its value, we just want to execute a market order.

Converting Pips To Ticks¶

When coding cBots, it is easy to encounter bugs arising from the fact that some variable values are calculated in units while other values are calculated in pips.

The below SymbolExtensions class showcases how pips can be converted to ticks. It also demonstrates how pips can be added to an absolute price value.

using System;
using cAlgo.API;
using cAlgo.API.Internals;

namespace Samples
{
    [Robot(AccessRights = AccessRights.None)]
    public class Sample : Robot
    {
        protected override void OnStart()
        {
            var spreadInPips = Symbol.NormalizePips(Symbol.ToPips(Symbol.Spread));

            Print(spreadInPips);

            var spreadInTicks = Math.Round(Symbol.ToTicks(Symbol.Spread));

            Print(spreadInTicks);

            /* Calculating a long position stop loss using the
            absolute price value. */
            var stopLossInPips = 60;

            /* We use 'NormalizePips' to avoid the 'invalid decimal places'
            error in case our stop loss value has too many decimals. */
            var stopLossInPrice = Symbol.Ask - (Symbol.NormalizePips(stopLossInPips) * Symbol.PipSize);

            Print(stopLossInPrice);
        }
    }

    public static class SymbolExtensions
    {
        /// <summary>
        /// Returns a symbol pip value
        /// </summary>
        /// <param name="symbol"></param>
        /// <returns>double</returns>
        public static double GetPip(this Symbol symbol)
        {
            return symbol.TickSize / symbol.PipSize * Math.Pow(10, symbol.Digits);
        }

        /// <summary>
        /// Returns a price value in terms of pips
        /// </summary>
        /// <param name="symbol"></param>
        /// <param name="price">The price level</param>
        /// <returns>double</returns>
        public static double ToPips(this Symbol symbol, double price)
        {
            return price * symbol.GetPip();
        }

        /// <summary>
        /// Returns a price value in terms of ticks
        /// </summary>
        /// <param name="symbol"></param>
        /// <param name="price">The price level</param>
        /// <returns>double</returns>
        public static double ToTicks(this Symbol symbol, double price)
        {
            return price * Math.Pow(10, symbol.Digits);
        }

        /// <summary>
        /// Rounds a price level to the number of symbol digits
        /// </summary>
        /// <param name="symbol">The symbol</param>
        /// <param name="price">The price level</param>
        /// <returns>double</returns>
        public static double Round(this Symbol symbol, double price)
        {
            return Math.Round(price, symbol.Digits);
        }

        /// <summary>
        /// Normalize x Pips amount decimal places to something that can be used as a stop loss or take profit for an order.
        /// For example if symbol is EURUSD and you pass to this method 10.456775 it will return back 10.5
        /// </summary>
        /// <param name="symbol">The symbol</param>
        /// <param name="pips">The amount of Pips</param>
        /// <returns>double</returns>
        public static double NormalizePips(this Symbol symbol, double pips)
        {
            var currentPrice = Convert.ToDecimal(symbol.Bid);

            var pipSize = Convert.ToDecimal(symbol.PipSize);

            var pipsDecimal = Convert.ToDecimal(pips);

            var pipsAddedToCurrentPrice = Math.Round((pipsDecimal * pipSize) + currentPrice, symbol.Digits);

            var tickSize = Convert.ToDecimal(symbol.TickSize);

            var result = (pipsAddedToCurrentPrice - currentPrice) * tickSize / pipSize * Convert.ToDecimal(Math.Pow(10, symbol.Digits));

            return decimal.ToDouble(result);
        }
    }
}

Using Historical Trades Data¶

When coding cBots, you have access to your account history. This means that you can iterate over your past trades and use their data for whatever purposes you have.

The below code snippet creates a CSV file containing all of our past trades and their trade data.

using System;
using cAlgo.API;
using System.Text;
using System.IO;

namespace Samples
{
    /* We provide the access rights required for
    reading and writing in locally stored files. */
    [Robot(AccessRights = AccessRights.FullAccess)]
    public class Sample : Robot
    {
        protected override void OnStart()
        {
            var stringBuilder = new StringBuilder();

            _ = stringBuilder.AppendLine($"PositionId,TradeType,SymbolName,VolumeInUnits,EntryTime,EntryPrice,ClosingTime,ClosingPrice,NetProfit,Balance");

            // All trades are inside the 'History' collection
            foreach (var trade in History)
            {
                _ = stringBuilder.AppendLine($"{trade.PositionId},{trade.TradeType},{trade.SymbolName},{trade.VolumeInUnits},{trade.EntryTime:o},{trade.EntryPrice},{trade.ClosingTime:o},{trade.ClosingPrice},{trade.NetProfit},{trade.Balance}");
            }

            // We will save the CSV file on our desktop
            var desktopPath = Environment.GetFolderPath(Environment.SpecialFolder.Desktop);

            var filePath = Path.Combine(desktopPath, $"{Account.Number}_History.csv");

            File.WriteAllText(filePath, stringBuilder.ToString());
        }
    }
}

Converting Lots to Units¶

The cTrader Automate API calculates volume in units instead of lots. However, most Forex traders are only familiar with lots as the measure of volume.

You can convert lots to units by using the Symbol.QuantityToVolumeUnits() method.

using System;
using cAlgo.API;
using System.Text;
using System.IO;

namespace Samples
{
    [Robot(AccessRights = AccessRights.None)]
    public class Sample : Robot
    {
        protected override void OnStart()
        {
            var lots = 2.5;

            var volumeInUnits = Symbol.QuantityToVolumeInUnits(lots);

            _ = ExecuteMarketOrder(TradeType.Sell, SymbolName, volumeInUnits);
        }
    }
}

Alternatively, you can use the Symbol.VolumeInUnitsToQuantity() method to convert units to lots.

Working With Colors¶

cBots can use custom colors when performing various operations (e.g., when displaying text on trading charts). To add color as a customizable parameter, add the following code to your parameter declarations.

[Parameter("Color", DefaultValue = "#f54242")]
public Color DrawingColor { get; set; }

Note that you can use both hexadecimal color codes and color names (such as "red") when defining the DefaultValue of such a parameter.

To illustrate how color parameters work, we will create a simple cBot that, upon being started, will write text on the trading chart on which it is operating. The color of this text will be customizable via the TextColor parameter.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo.Robots
{
    [Robot(AccessRights = AccessRights.None)]
    public class SampleColorcBot : Robot
    {
        [Parameter("Text Color", DefaultValue = "red")]
        public Color TextColor { get; set; }

        protected override void OnStart()
        {
            var staticText = Chart.DrawStaticText("static", "Sample text to demonstrate how color works", VerticalAlignment.Center, HorizontalAlignment.Center, TextColor);

        }

    }
}

Last update: September 29, 2023