Skip to content

Trading

Note

For a more detailed understanding, we also provide specific API Reference

Introduction

cBots are automated strategies that can execute trades without your presence or monitoring. One can code cBots using the cAlgo editor, backtest them for verification and finally execute them. You simply need to start a cBot and you have the option to stop it manually or programmatically. cBots facilitate entering trades more accurately. The key advantage of automated trading is that it can send orders faster than a person.

The new trading API of cAlgo provides synchronous as well as asynchronous trade operation methods. Synchronous operation means that each statement in the code will be completed before execution proceeds to the next.

We will start by describing synchronous methods and then will cover asynchronous methods later.

We use examples of cBots in this manual but note that these cBots are not designed to produce any profit. They are intended for instructional purposes only. Furthermore, this guide assumes some basic knowledge of the C# programming language.

The New cBot Template

To load the new cBot template into the text editor; click on the cBots tab and then the new button next to the search. The cBot attribute, with optional properties listed, such as the Timezone, has to precede the cBot class declaration.

The OnStart method is called upon initialization of the cBot. The OnTick method is called each time there is a new tick and the OnStop method is called when the cBot stops.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
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 NewcBot
{
    [Robot(AccessRights = AccessRights.None)]
    public class NewcBot : Robot
    {
        [Parameter(DefaultValue = "Hello world!")]
        public string Message { get; set; }

        protected override void OnStart()
        {
            // To learn more about cTrader Automate visit our Help Center:
            // https://help.ctrader.com/ctrader-automate

            Print(Message);
        }

        protected override void OnTick()
        {
            // Handle price updates here
        }

        protected override void OnStop()
        {
            // Handle cBot stop here
        }
    }
}

Market Orders

Example 1 - Simple cBot with successful result

The following simple cBot creates a market order upon start up and saves the result in a variable called “result”. If the order execution is successful the entry price is printed to the log.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            var result = ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000);

            if (result.IsSuccessful)
            {
                var position = result.Position;
                Print("Position entry price is {0}", position.EntryPrice);
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, m1.
  • Executing Market Order to Buy 10k EURUSD
  • Executing Market Order to Buy 10k EURUSD SUCCEEDED, Position PID156168
  • Position entry price is 1.34577

Example 2 - Simple cBot with unsuccessful result

If we modify the volume parameter in the previous example to 1 which is not a valid value for volume we will get the error printed in the log. We can further modify the cBot to stop in case there is an error.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            var result = ExecuteMarketOrder(TradeType.Buy, SymbolName, -1);

            if (!result.IsSuccessful) Stop();
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Executing Market Order to Buy -1 EURUSD
  • Executing Market Order to Buy -1 EURUSD FAILED with error "BadVolume"
  • cBot "Sample_cBot" was stopped for EURUSD, h1.

Example 3 - Execute market order with more parameters

The previous example uses the minimum parameters in the ExecuteMarketOrder method, which are the trade type, the symbol and the volume. The additional optional parameters are label, stop loss, take profit, slippage and the comment.

The next example specifies the label and protection as well.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
using cAlgo.API;

namespace NewcBot
{
    [Robot(TimeZone = TimeZones.UTC)]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            var result = ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000, "order 1", 10, 10);

            if (result.IsSuccessful)
            {
                var position = result.Position;
                Print("Position entry price is {0}", position.EntryPrice);
                Print("Position SL price is {0}", position.StopLoss);
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, m1.
  • Executing Market Order to Buy 10k EURUSD (SL: 10, TP: 10)
  • Executing Market Order to Buy 10k EURUSD (SL: 10, TP: 10) SUCCEEDED, Position ID156169
  • Position entry price is 1.34693
  • Position SL price is 1.34593

Modify Position

In the next example we will add only take profit when the order is executed and then we will modify the position to add stop loss as well. In order to omit the stop loss parameter we have to write null in its place. Example 1 – Modify take profit

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class SamplecBbot : Robot
    {
        protected override void OnStart()
        {
            var result = ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000, "order 1", null, 10);

            if (result.IsSuccessful)
            {
                var position = result.Position;
                Print("Position SL price is {0}", position.StopLoss);

                var stopLoss = position.EntryPrice - 10*Symbol.PipSize;
                ModifyPosition(position, stopLoss, position.TakeProfit);

                Print("New Position SL price is {0}", position.StopLoss);

            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, m1.
  • Executing Market Order to Buy 10000 EURUSD (TP: 10)
  • Executing Market Order to Buy 10000 EURUSD (TP: 10) SUCCEEDED, Position PID5229848
  • Position SL price is null
  • Modifying position PID5229848 (SL: 1.07716, TP: 1.07916)
  • Modifying position PID5229848 (SL: 1.07716, TP: 1.07916) SUCCEEDED, Position PID5229848
  • New Position SL price is 1.07716

Close Position

Example 1 – Close position

The code illustrated next creates a market order and if the position gross profit is above a certain value it closes the position.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000, "myLabel");
        }

        protected override void OnTick()
        {
            var position = Positions.Find("myLabel");
            if (position != null && position.GrossProfit > 10)
            {
                ClosePosition(position);
                Stop();
            }   
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, m1.
  • Executing Market Order to Buy 10k EURUSD
  • Executing Market Order to Buy 10k EURUSD SUCCEEDED, Position PID156171
  • Closing position PID156171
  • Closing position PID156171 SUCCEEDED, Position PID156171
  • cBot "Sample_cBot" was stopped for EURUSD, m1.

Example 2 - Partial Close

We will modify the previous example to create two market orders with the same labels. On each incoming new bar, the cBot will look for the order with one of the two labels and close only half of it, if the volume is equal to or greater than 20,000.

Here we illustrate the method FindAll which returns an array of positions that we can loop through.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            ExecuteMarketOrder(TradeType.Buy, SymbolName, 20000, "myLabel");
            ExecuteMarketOrder(TradeType.Buy, SymbolName, 30000, "myLabel");
        }

        protected override void OnBar()
        {
            var positions = Positions.FindAll("myLabel", SymbolName, TradeType.Buy);

            foreach (var position in positions)
            {
                if (position.VolumeInUnits >= 20000)
                {
                    ClosePosition(position, 15000);
                }
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Executing Market Order to Buy 20k EURUSD
  • Executing Market Order to Buy 20k EURUSD SUCCEEDED, Position PID664437
  • Executing Market Order to Buy 30k EURUSD
  • Executing Market Order to Buy 30k EURUSD SUCCEEDED, Position PID664438
  • Closing position PID664437 (15k)
  • Closing position PID664437 (15k) SUCCEEDED, Position PID664437
  • Closing position PID664438 (15k)
  • Closing position PID664438 (15k) SUCCEEDED, Position PID664438

Pending Orders

Example 1 – Simple cBot with Limit and Stop Orders

Limit and Stop orders are Pending Orders. They are created in a similar way to market orders.

Their parameters differ in that the target price must be specified and there is no market range. The next cBot creates two limit orders and a stop order. It then, loops through the orders and prints their label and Id(s) to the log.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            PlaceLimitOrder(TradeType.Buy, SymbolName, 10000, Symbol.Bid, "myLimitOrder");
            PlaceLimitOrder(TradeType.Buy, SymbolName, 20000, Symbol.Bid-2*Symbol.PipSize, "myLimitOrder");            
            PlaceStopOrder(TradeType.Buy, SymbolName, 10000, Symbol.Ask, "myStopOrder");

            foreach (var pendingOrder in PendingOrders)
            {
                Print("Order placed with label {0}, id {1}", pendingOrder.Label, pendingOrder.Id);
            }                                
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, m1.
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.34211)
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.34211) SUCCEEDED, PendingOrder OID246324
  • Placing Limit Order to Buy 20k EURUSD (Price: 1.34191)
  • Placing Limit Order to Buy 20k EURUSD (Price: 1.34191) SUCCEEDED, PendingOrder OID246325
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.34243)
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.34243) SUCCEEDED, PendingOrder OID246326
  • Order placed with label myLimitOrder, id 246324
  • Order placed with label myLimitOrder, id 246325

Example 2 – Simple cBot with pending orders initialized with more parameters

Just as with market orders you may also specify the representing label, protection, expiry date and time and comment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
using cAlgo.API;
using System;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            DateTime midnight = Server.Time.AddDays(1).Date;

            PlaceLimitOrder(TradeType.Buy, SymbolName, 10000, Symbol.Bid, "mySample_cBot", 10, null, midnight, "First");

            PlaceStopOrder(TradeType.Buy, SymbolName, 10000, Symbol.Ask, "mySample_cBot", 10, 10, null, "Second");

            foreach (var order in PendingOrders)
            {
                var sl = order.StopLoss == null ? "" : "SL: " + order.StopLoss;
                var tp = order.TakeProfit == null ? "" : " TP: " + order.TakeProfit;

                var text = string.Format("{0} {1}", sl, tp);

                if (order.OrderType == PendingOrderType.Limit)
                    Print(order.Comment + " Limit Order " + text);
                else
                    Print(order.Comment + " Stop Order " + text);
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, m1.
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.34326, SL: 10, ExpireTime: 22/11/2013 00:00)
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.34326, SL: 10, ExpireTime: 22/11/2013 00:00), SUCCEEDED, PendingOrder OID246369
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.34359, SL: 10, TP: 10)
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.34359, SL: 10, TP: 10) SUCCEEDED, PendingOrder OID246370
  • First Limit Order SL: 1.34226
  • Second Stop Order SL: 1.34259 TP: 1.34459

Modify Pending Orders

Example 1 – Modify the target price of pending orders placed by this cBot

To modify the target price of a pending order, the protection levels or the expiration date time we use syntax such as in the following example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
using cAlgo.API;
using System;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            var price = Symbol.Ask + 10 * Symbol.PipSize;
            DateTime? expiry = Server.Time.AddHours(12);
            PlaceStopOrder(TradeType.Buy, SymbolName, 10000, price, "myLabel", 10, 10, expiry);
        }

        protected override void OnBar()
        {
            foreach (var order in PendingOrders)
            {
                if (order.Label == "myLabel")
                {
                    double newPrice = Symbol.Ask + 5 * Symbol.PipSize;
                    ModifyPendingOrder(order, newPrice, order.StopLossPips, 
                                                                order.TakeProfitPips, order.ExpirationTime);
                }
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.36161, SL: 10, TP: 10, ExpireTime: 27/11/2013 21:59)
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.36161, SL: 10, TP: 10, ExpireTime: 27/11/2013 21:59) SUCCEEDED, PendingOrder OID1081885
  • Modifying pending order OID1081885 (Price: 1.36109, SL: 10, TP: 10, ExpireTime: 27/11/2013 21:59)
  • Modifying pending order OID1081885 (Price: 1.36109, SL: 10, TP: 10, ExpireTime: 27/11/2013 21:59) SUCCEEDED, PendingOrder OID1081885

Cancel Pending Orders

The cancel an order the syntax is CancelPendingOrder(order); Where order is of type PendingOrder.

Example 1 - Cancel all the orders that have the label “myLabel”.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
using cAlgo.API;
using System;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnTick()
        {
            foreach (var order in PendingOrders)
            {
                if (order.Label == "myLabel")
                {
                    CancelPendingOrder(order);
                }
            }
        }
    }
}

Position Events

Example 1 – Subscribe event to Positions

To test when a position is opened we can subscribe an event to Positions. This event will also be raised if a position opens manually or by another cBot.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            Positions.Opened += PositionsOnOpened;
            ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000, "myLabel", 10, 10);
        }

        private void PositionsOnOpened(PositionOpenedEventArgs args)
        {
            var pos = args.Position;
            Print("Position opened at {0}", pos.EntryPrice);
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, m1.
  • Executing Market Order to Buy 10k EURUSD (SL: 10, TP: 10)
  • Executing Market Order to Buy 10k EURUSD (SL: 10, TP: 10) SUCCEEDED, Position PID157201
  • Position opened at 1.34342

Similarly, we can subscribe events that will be raised each time a position is closed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            Positions.Closed += PositionsOnClosed;
            ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000, "myLabel", 10, 10);
        }

        protected override void OnBar()
        {
            var position = Positions.Find("myLabel");
            if (position != null)
                ClosePosition(position);
        }

        private void PositionsOnClosed(PositionClosedEventArgs args)
        {
            var pos = args.Position;
            Print("Position closed with {0} profit", pos.GrossProfit);
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURGBP, m1.
  • Executing Market Order to Buy 10k EURGBP (SL: 10, TP: 10)
  • Executing Market Order to Buy 10k EURGBP (SL: 10, TP: 10) SUCCEEDED, Position PID50038
  • Closing position PID50038
  • Closing position PID50038 SUCCEEDED, Position PID50038
  • Position closed with -0.24 profit

Asynchronous execution

What we have been describing thus far, is implementing cBots using synchronous trade operation methods. Synchronous operation is more intuitive and straight forward as far as coding is concerned.

Synchronous trade operation methods, send requests to the server and wait for the server response, then pass execution to the statements that follow.

In asynchronous operation, when a request is send to the server, the program continues to execute the next statements, without waiting for the response from the server.

The statements that follow the asynchronous trade operation request cannot assume anything about the result of those requests.

For example, if the program sends a request to execute a market order and then continues to place a limit order, the request to place a limit order will most probably be send to the server before the response is received, that position is opened, for instance when the server response is received, the program can pass execution control to a callback function, then the necessary statements will be executed according to whether the operation was successful or not.

We cover callbacks at the end of this section.

The benefit of using asynchronous execution is that a potentially time consuming process of waiting for the response from the server is avoided. Instead, execution continues and when the response arrives, control is passed to a callback if one is specified. Do not confuse asynchronous operation with multi-threading.

At any given time only one method can be invoked. cAlgo never invokes your methods in parallel so you don’t have to worry about multi-threading issues.

Execute Market Orders Asynchronously

The syntax of the asynchronous methods is very similar to that of the synchronous ones. They accept the same type of argument lists. The main difference is that the return type is TradeOperation instead of TradeResult. Example 1 - Simple cBot

The following simple cBot demonstrates asynchronous operation. A market order is created and then it tests if the operation is executing in the next statement.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            TradeOperation operation = ExecuteMarketOrderAsync(TradeType.Buy, SymbolName, 10000);

            if (operation.IsExecuting)
            {
                Print("Operation Is Executing");
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURGBP, m1.
  • Executing Market Order to Buy 10k EURGBP
  • Operation Is Executing
  • Executing Market Order to Buy 10k EURGBP SUCCEEDED, Position PID50039

Example 2 - Simple cBot – Execution order

In the next example a combination of an asynchronous method and a synchronous method is used to demonstrate the difference between the two.

The cBot tests if an operation is executing right after the asynchronous one and then again after the synchronous one.

As you can see in the log output, the results are different.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            TradeOperation operation = ExecuteMarketOrderAsync(TradeType.Buy, SymbolName, 10000);
            Print(operation.IsExecuting ? "Operation Is Executing" : "Operation executed");
            ExecuteMarketOrder(TradeType.Buy, SymbolName, 20000);
            Print(operation.IsExecuting ? "Operation Is Executing" : "Operation executed");

        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Executing Market Order to Buy 10k EURUSD
  • Operation Is Executing
  • Executing Market Order to Buy 20k EURUSD
  • Executing Market Order to Buy 10k EURUSD SUCCEEDED, Position PID159131
  • Executing Market Order to Buy 20k EURUSD SUCCEEDED, Position PID159132
  • Operation executed

Example 3 – More parameters

The following cBot creates an order specifying a label and protection as well as the minimum parameters trade type, symbol and volume.

Also, the Positions collection and the method FindAll are demonstrated.

Find and FindAll can be used to query positions of the same label, symbol and trade type.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            ExecuteMarketOrderAsync(TradeType.Buy, SymbolName, 10000, "myLabel", 10, 10);
        }
        protected override void OnTick()
        {
            Position[] positions = Positions.FindAll("myLabel", SymbolName, TradeType.Buy);
            if (positions.Length == 0)
                return;

            foreach (var position in positions)
                Print("Buy at {0} SL {1}", position.EntryPrice, position.StopLoss);

            Stop();
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Executing Market Order to Buy 10k EURUSD (SL: 10, TP: 10)
  • Executing Market Order to Buy 10k EURUSD (SL: 10, TP: 10) SUCCEEDED, Position PID662608
  • Buy at 1.35148 SL 1.35048
  • cBot "Sample_cBot" was stopped for EURUSD, h1.

Modify Position Asynchronously

Example 1 – Modify a positions protection.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            ExecuteMarketOrderAsync(TradeType.Buy, SymbolName, 10000, "myLabel", null, 10);
        }

        protected override void OnTick()
        {
            Position myPosition = Positions.Find("myLabel");
            if (myPosition != null && myPosition.StopLoss == null)
            {
                double stopLoss = Symbol.Bid - 10 * Symbol.PipSize;
                ModifyPositionAsync(myPosition, stopLoss, myPosition.TakeProfit);
            }
        }
    }
}
```c# linenums="1"

!!! abstract "Log output"
    * cBot "Sample_cBot" was started successfully for EURUSD, h1.
    * Executing Market Order to Buy 10k EURUSD (TP: 10)
    * Executing Market Order to Buy 10k EURUSD (TP: 10) SUCCEEDED, Position PID662667
    * Modifying position PID662667 (SL: 1.35083, TP: 1.35286)
    * Modifying position PID662667 (SL: 1.35083, TP: 1.35286) SUCCEEDED, Position PID662667

### Close Position Asynchronously

Example 1 – Closes a position.

The next example demonstrates closing a position asynchronously if the position exists.

The Find method is used to query the Positions collection for the position with a specific label.

```c# linenums="1"
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            ExecuteMarketOrderAsync(TradeType.Buy, SymbolName, 10000, "myLabel", null, 10);
        }

        protected override void OnTick()
        {
            Position myPosition = Positions.Find("myLabel");
            if (myPosition != null && myPosition.GrossProfit > 10)
            {
                ClosePosition(myPosition);
                Stop();
            }         
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Executing Market Order to Buy 10k EURUSD (TP: 10)
  • Executing Market Order to Buy 10k EURUSD (TP: 10) SUCCEEDED, Position PID662667
  • Modifying position PID662667 (SL: 1.35083, TP: 1.35286)
  • Modifying position PID662667 (SL: 1.35083, TP: 1.35286) SUCCEEDED, Position PID662667

Place Pending Orders Asynchronously

As with synchronous methods placing pending orders is similar to executing market orders.

The arguments only differ in that the target price is required, the market range is not in the argument list and there is another optional parameter the expiration date of the order.

Example 1 – Place Limit and Stop orders

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
using cAlgo.API;
using System;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            DateTime expiry = Server.Time.AddHours(12);
            PlaceLimitOrderAsync(TradeType.Buy, SymbolName, 10000, Symbol.Bid, "myLabel", null, null, expiry);
            PlaceStopOrderAsync(TradeType.Buy, SymbolName, 10000, Symbol.Ask + 10 * Symbol.PipSize, "myLabel", null, null, expiry);
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.35098, ExpireTime: 25/11/2013 22:43)
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.35202, ExpireTime: 25/11/2013 22:43)
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.35098, ExpireTime: 25/11/2013 22:43) SUCCEEDED, PendingOrder OID1078417
  • Placing Stop Order to Buy 10k EURUSD (Price: 1.35202, ExpireTime: 25/11/2013 22:43) SUCCEEDED, PendingOrder OID1078418

Modify Pending Orders Asynchronously

Example 1 – Modify Limit order asynchronously

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
using cAlgo.API;
using System;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            DateTime expiry = Server.Time.AddHours(12);
            PlaceLimitOrderAsync(TradeType.Buy, SymbolName, 10000, Symbol.Bid, "myLabel", null, 10, expiry);
        }

        protected override void OnTick()
        {
            foreach (var order in PendingOrders)
            {
                if (order.Label == "myLabel" && order.StopLoss == null)
                {
                    ModifyPendingOrderAsync(order, order.TargetPrice, 10, 10, null);
                }
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.34988, TP: 10, ExpireTime: 26/11/2013 02:56)
  • Placing Limit Order to Buy 10k EURUSD (Price: 1.34988, TP: 10, ExpireTime: 26/11/2013 02:56) SUCCEEDED, PendingOrder OID1079080
  • Modifying pending order OID1079080 (Price: 1.34988, SL: 10, TP: 10, ExpireTime: null)
  • Modifying pending order OID1079080 (Price: 1.34988, SL: 10, TP: 10, ExpireTime: null) |SUCCEEDED, PendingOrder OID1079080

Cancel Pending Orders Asynchronously

Example 1 – Cancel all pending orders.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnBar()
        {
            foreach (var pendingOrder in PendingOrders)
            {
                var result = CancelPendingOrderAsync(pendingOrder);

                if (result.IsExecuting)
                {
                    Print("Executing");
                }
                else
                {
                    Print("Already completed");
                }
            }
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Cancelling pending order OID253328
  • Cancelling pending order OID253328 SUCCEEDED, PendingOrder OID253328

Example 2 – Cancel pending orders with label myLabel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnBar()
        {
            foreach (var pendingOrder in PendingOrders)
            {
                if (pendingOrder.Label == "myLabel")
                {
                    CancelPendingOrderAsync(pendingOrder);
                }
            }
        }
    }
}

Callbacks for Asynchronous methods

Using asynchronous mode often requires controlling execution once a result is returned from the server.

To handle this one can add a callback function at the end of the list of parameters of all asynchronous methods.

This callback function is called once the response from the server is received, for instance when a position is opened, modified or closed or a pending order filled.

Example 1 – Asynchronous Market order with callback

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            TradeOperation operation = ExecuteMarketOrderAsync(TradeType.Buy, SymbolName, 10000, PositionOpened);

            if (operation.IsExecuting)
                Print(operation.ToString());
            else
                Print(operation.TradeResult.ToString());
        }

        private void PositionOpened(TradeResult tradeResult)
        {
            var position = tradeResult.Position;
            Print(tradeResult.ToString());
            if (tradeResult.IsSuccessful)
                Print("Position {0} opened at {1}", position.Id, position.EntryPrice);
        }
    }
}

Log output

  • cBot "Sample_cBot" was started successfully for EURUSD, h1.
  • Executing Market Order to Buy 10k EURUSD
  • TradeOperation (Executing Market Order to Buy 10k EURUSD EXECUTING)
  • Executing Market Order to Buy 10k EURUSD SUCCEEDED, Position PID663313
  • TradeResult (Success, Position: PID663313)
  • Position 663313 opened at 1.35098

Example 2 – Using Lambda expressions

Instead of defining a callback method one can use lambda expressions.

In the following example, when the order is placed the result description will be printed to the log.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
using cAlgo.API;

namespace NewcBot
{
    [Robot()]
    public class Sample_cBot : Robot
    {
        protected override void OnStart()
        {
            PlaceLimitOrderAsync(TradeType.Buy, SymbolName, 10000, Symbol.Ask - 20 * Symbol.PipSize, "myLabel", result => Print(result.ToString()));
        }
    }
}

Trading Other Symbols

You can develop a cBot that trades multiple symbols not just the attached chart symbol, for that you have to use the Symbols API.

Symbols is a collection of all available symbols of your trading account, you can iterate over it by using a loop or you can find a specific symbol on it.

Usually on multi symbol cBots you need some properties of a symbol like:

  • Minimum Allowed Volume
  • Maximum Allowed Valume
  • Volume Step
  • Pip/Tick Size
  • Pip/Tick Value (Monetary value of one Pip/Tick of a symbol in account currency)

You can get all of the above properties from a Symbol object instance, for example lets find a symbol with the name of "GBPUSD" and then create a market order for it and use it's minimum allowed volume as order volume:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
using cAlgo.API;

namespace NewcBot
{
    [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);
            }
        }
    }
}

Calculating Risk Percentage for Positions/Orders

Most traders use x% of their account on a position/order, you can calculate risk percentage for a symbol and then use that amount of volume for a position/order.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
using System;
using cAlgo.API;
using cAlgo.API.Internals;

namespace Samples
{
    [Robot(AccessRights = AccessRights.None)]
    public class RiskPercentageSample : Robot
    {
        [Parameter("Risk %", DefaultValue = 1, MinValue = 0.1, MaxValue = 100)]
        public double RiskPercentage { get; set; }

        [Parameter("Stop Loss (Pips)", DefaultValue = 100, MinValue = 0)]
        public double StopLossInPips { get; set; }

        protected override void OnStart()
        {
            // You can also use Account.Equity instead of Balance
            var volume = Symbol.GetVolume(RiskPercentage, Account.Balance, StopLossInPips);

            _ = ExecuteMarketOrder(TradeType.Buy, SymbolName, volume, string.Empty, StopLossInPips, default);
        }
    }

    public static class SymbolExtensions
    {
        /// <summary>
        /// Returns the amount of risk percentage based on stop loss amount
        /// </summary>
        /// <param name="symbol">The symbol</param>
        /// <param name="stopLossInPips">Stop loss amount in Pips</param>
        /// <param name="accountBalance">The account balance</param>
        /// <param name="volume">The volume amount in units (Not lots)</param>
        /// <returns>double</returns>
        public static double GetRiskPercentage(this Symbol symbol, double stopLossInPips, double accountBalance, double volume)
        {
            return Math.Abs(stopLossInPips) * symbol.PipValue / accountBalance * 100.0 * volume;
        }

        /// <summary>
        /// Returns the amount of stop loss in Pips based on risk percentage amount
        /// </summary>
        /// <param name="symbol">The symbol</param>
        /// <param name="riskPercentage">Risk percentage amount</param>
        /// <param name="accountBalance">The account balance</param>
        /// <param name="volume">The volume amount in units (Not lots)</param>
        /// <returns>double</returns>
        public static double GetStopLoss(this Symbol symbol, double riskPercentage, double accountBalance, double volume)
        {
            return riskPercentage / (symbol.PipValue / accountBalance * 100.0 * volume);
        }

        /// <summary>
        /// Returns the amount of volume based on your provided risk percentage and stop loss
        /// </summary>
        /// <param name="symbol">The symbol</param>
        /// <param name="riskPercentage">Risk percentage amount</param>
        /// <param name="accountBalance">The account balance</param>
        /// <param name="stopLossInPips">Stop loss amount in Pips</param>
        /// <returns>double</returns>
        public static double GetVolume(this Symbol symbol, double riskPercentage, double accountBalance, double stopLossInPips)
        {
            return symbol.NormalizeVolumeInUnits(riskPercentage / (Math.Abs(stopLossInPips) * symbol.PipValue / accountBalance * 100));
        }
    }
}

You can also use the two other methods of above SymbolExtensions for getting risk percentage or amount of stop loss in pips.

Converting Pips To Ticks

Usually when you develop a cBot you face this issue a lot you want to change some value from Pips to ticks or vice versa.

Or you may want to add/subtract x number of Pips/Ticks to an absolute price value, this is the main cause of lots of bugs in cBots as developers forget the unit of their variable values.

You can use the below Symbol extensions class for converting Pips to Ticks or adding Pips to an absolute price value:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
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 in absolute price
            var stopLossInPips = 60;
            // We use NormalizePips to avoid 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 Historcial Trades Data

cTrader Automate API gives you access to all of your account history, you can iterate over each trade and access their data.

Let's create a CSV file that will contain all of our trading account trade history with each trade data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
using System;
using cAlgo.API;
using System.Text;
using System.IO;

namespace Samples
{
    // Change the access rights to we will be able to
    // write on 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 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 your desktop
            var desktopPath = Environment.GetFolderPath(Environment.SpecialFolder.Desktop);

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

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

Check the Trade on API references to find all it's properties.

Converting Lots to Volume in Units

cTrader Automate API uses volume in units not lots, but most Forex traders are only familiar with lots or quantity.

You can easily convert lots to volume in units by using Symbol QuantityToVolumeInUnits method, example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
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);
        }
    }
}

You can also use Symbol VolumeInUnitsToQuantity method to change volume in units to lots.

Last update: June 26, 2022

Comments