Local storage

In this guide, we explain how you can work with local storage when developing cTrader algos. Below, we provide a one-minute summary of how local storage access works.

Local storage in one minute!

Local storage allows you to save information in your local file system. Use it to persist data between two or more deployments of your cBots and indicators.
To save data, use the SetString(string key, string value) and SetObject(string key, object obj) methods. To retrieve it, invoke the GetString(string key) and T GetObject<T>(string key) methods.
Specify your preferred local storage scope by using the LocalStorageScope enum. For example, the SetString(string key, string value, LocalStorageScope.Device) overload will save data in your Documents/cAlgo/LocalStorage/ directory.
While information is saved automatically every minute, you can use the Flush(LocalStorageScope localStorageScope) method to store data without delays.
During backtesting and optimisation, local storage stores data in memory only.

Using local storage

Think of local storage as a way to store information between one or several stops and starts of your cBots and indicators. This feature allows for saving cBot and indicator data and then accessing this information in several ways depending on your needs. Local storage works regardless of the access rights given to an algo.

The LocalStorage interface contains all methods that you can use to store and access data to and from local storage. Some examples of these methods include the following:

SetString(string key, string value)- saves a string value by matching it with the specified key.
SetObject(string key, object obj)- saves an object by matching it with the specified key.
GetString(string key) - retrieves a saved string value by finding it under the specified key.
T GetObject<T>(string key) - retrieves a saved object of type T from local storage by finding it under the specified key.

Warning

The SetObject(string key, object obj) and GetObject<T>(string key) methods only work with data types that can be serialised (converted into bytes).

Consider the following example in which we ask a cBot instance to save an example message on start. On subsequent starts, the same instance will display a message box containing our message.

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 SampleLocalStorageTest : Robot

    {

        protected override void OnStart()
        {

            string messageLocalStorage = LocalStorage.GetString("Example Message");

            if (messageLocalStorage is not null)

            {

                MessageBox.Show(messageLocalStorage);

            }

            LocalStorage.SetString("Example Message", "This is just an example message");
        }
    }
}

After an instance of the cBot above is launched for the first time, it saves our example message in local storage. After stopping the instance and starting it again, the following message box is shown.

Note that local storage works even when AccessRights.None is specified.

Define local storage scope

The local storage scope (defined via the LocalStorageScope type) determines where exactly information is stored and how it can be accessed. This enum contains the following constants:

LocalStorageScope.Instance - saved data is stored and can only be accessed by a specific running instance of a cBot or indicator. Information is saved to the Documents/cAlgo/LocalStorage/{AlgoType}/{AlgoName}/{InstanceUniqueIdentifier}/ directory. In this path, "AlgoType" denotes the type of the cTrader extension working with local storage (cBots or Indicators) while AlgoName is the name of a specific cBot/indicator. InstanceUniqueIdentifier is the unique ID of a specific instance of a particular cBot or indicator.
LocalStorageScope.Type - saved data is stored and can be accessed by all running instances of a particular cBot or indicator. Information is saved to the Documents/cAlgo/LocalStorage/{AlgoType}/{AlgoName}/ directory.
LocalStorageScope.Device - saved data is stored and can be accessed by all running instances of cBots and indicators on the current device. Information is saved to the "Documents/cAlgo/LocalStorage/" directory.

In turn, methods such as SetString() and SetObject() have additional overloads allowing for specifying a custom local storage scope. For example, the following code will save a string to LocalStorageScope.Type; this string, subsequently, will be accessible to all extensions of a particular type.

SetString(“Example String”, “Just an example string”, LocalStorageScope.Type);

If LocalStorageScope is not specified as a parameter, LocalStorageScope.Instance is used by default.

Note that this behaviour is different for the GetString(string key) and T GetObject<T>(string key) methods. When these methods are invoked without specifying the local storage scope, they will search for the specified key in all scopes following the below hierarchy:

Instance
Type
Device

Additionally, each different local storage scope has its own disk space quota:

LocalStorageScope.Instance is limited to 10 MB.
LocalStorageScope.Type is limited to 100 MB.
LocalStorageScope.Device is limited to 500 MB.

The limits defined above are not cumulative. For example, if you have already used all 500 MB of device-level storage, you will still be able to store information using instance-level storage until reaching its limit of 10 MB.

How saving and loading information works

When storing information to local storage (for example, by invoking the SetString() method), cTrader automatically saves data every minute. Data is also saved on instance stop.

However, you can customise this behaviour by using the following methods:

Flush(LocalStorageScope localStorageScope) - saves all data to the specified scope.
Reload(LocalStorageScope localStorageScope) - reloads all values from the specified scope.

Keep in mind that, when calling the Reload(LocalStorageScope localStorageScope method, any pending changes may be lost. To avoid this, make sure to invoke Flush(LocalStorageScope localStorageScope) beforehand.

In the example below, we ask a cBot to execute a market order. After this action is completed, we immediately save the gross P&L of the position we have just opened in LocalStorageScope.Type.

ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000, “Custom label”);
var positionOne = Positions.Find("Custom label");        
string positionOneGrossProfit = positionOne.GrossProfit.ToString();
LocalStorage.SetString("Position 1", positionOneGrossProfit, LocalStorageScope.Device); 
LocalStorage.Flush(LocalStorageScope.Device);

Local storage in backtesting and optimisation

Local storage works differently in backtesting compared to real-time trading.

As shown previously, local storage uses the file system of your local machine when this feature is used in real-time trading. However, using the file system in backtesting would lead to several issues, most notably saving large amounts data that beard no relation to current market movements and trading operations.

To avoid these problems, all operations with local storage are conducted in memory only when performing backtests or optimising your cBots. As a result, you can be sure that all data saved to your file system only concerns real-time trading.

In summary, local storage is a highly beneficial feature of the Algo API that allows for persisting data between multiple stops and starts of various cBots and indicators. By using local storage effectively, you can create complex automated trading strategies based on custom data saved in your file system.