Strategy Inputs and Results #

Strategy Configuration #

Each strategy is executed in two steps: first, the engine iterates over the tools and checks whether they return positive results (this process is also known as giving ‘permission’ to continue execution); then, if positive results are received from all the tools, the outcomes are executed. These steps are represented by the strategy configuration structure and its two main sections: tools and outcomes.

{
	"description": "a simple strategy",
	"candle_interval": "5mins",
	"timeout": "18m15s",
	"tools": [
		{
			"type": "placeholder",
			"permit": true
		},
		{
			"type": "placeholder",
			"permit": true
		}
	],
	"outcomes": [
		{
			"type": "placeholder"
		},
		{
			"type": "placeholder"
		}
	]
}

description - string (optional; default: unused)
The description of the strategy and its purpose.
candle_interval - string
The candle interval that is used by all tools and outcomes. Possible interval values can be retrieved by sending a request to the exchange intervals retrieval endpoint.
timeout - string (duration; optional; default: unused)
The amount of time the strategy is given to complete. It cannot be a negative value.
If the value is zero or not provided, there is no time limit.
tools - array of objects
The array of tools to execute. Even though each type of tool has its own set of properties, they all have a type that indicates how their configuration structure should be loaded and executed. At least one tool must be specified.

Tools are executed in the order they are provided. Even if some root-level tool does not produce a positive result or returns an error, all other root-level tools are still executed.

Note that this does not apply to tools that wrap other tools, like the sequence tool, whose configuration options determine whether the execution of their wrapped entities should continue when a negative result is produced or not.

Also, if at least one root-level tool fails or produces a negative result, no outcomes are executed.
outcomes - array of objects
The array of outcomes to execute when all tools produce positive results (give their ‘permission’). Even though each type of outcome has its own set of properties, they all have a type that indicates how their configuration structure should be loaded and executed. At least one outcome must be specified.

Outcomes are executed in the order they are provided. Even if some root-level outcome returns an error, all other root-level outcomes are still executed.

Note that this does not apply to outcomes that wrap other outcomes, like the sequence outcome, whose configuration options determine whether the execution of their wrapped entities should continue when a negative result is produced or not.

Strategy Report #

When a strategy completes its execution, it produces an extensive report containing calculation values and results from all tools and outcomes. This report shows what decisions the engine made, how those decisions were influenced by the strategy’s configuration and, most importantly, why one decision was made instead of another. In other words, a report provides evidence that the engine did not lose its course or made some strange, undocumented actions.

The strategy report structure resembles that of the strategy configuration’s as it contains the same two main sections: tools and outcomes. Both of them contain reports of their respective tools and outcomes in the same order as they are specified in the strategy configuration. This means that, for example, the report of the first tool in the strategy configuration’s tools section is placed as the first element in the strategy report’s tools section.

The report has one more section that is just as important for result inspection as tools and outcomes, and that is exchange. It contains a snapshot of exchange data that was used during the strategy’s execution.

{
	"tools": [
		{
			"type": "placeholder",
			"permit": true
		},
		{
			"type": "placeholder",
			"error": "invalid data"
		}
	],
	"outcomes": [
		{
			"type": "placeholder"
		},
		{
			"type": "placeholder",
			"error": "invalid data"
		}
	],
	"exchange": {
		"candles": [
			{
				"opened_at": "2020-09-10T21:00:20Z",
				"open": "2",
				"high": "3",
				"low": "4",
				"close": "5",
				"volume": "6"
			},
			{
				"opened_at": "2020-09-10T21:05:20Z",
				"open": "3",
				"high": "4",
				"low": "5",
				"close": "6",
				"volume": "7"
			}
		]
	}
}

tools - array of objects
The array of tool reports. Even though each type of tool report has its own set of properties, they all have a type property that indicates how their structure should be parsed and represented.

If a tool produces no errors during its execution, a permit property that indicates whether other tools and outcomes should be executed is included in its report. However, if an error does occur, all standard report properties except type are omitted, and a special error property is added.
The type of each report is the same as its tool’s.
outcomes - array of objects
The array of outcome reports. Even though each type of outcome has its own set of properties, they all have a type that indicates how their structure should be parsed and represented. Note that if at least one tool does not produce a positive result (give their ‘permission’), the outcomes are not executed, which in turn means that this array is not included in the report.

If an error occurs during an outcome’s execution, all standard report properties except type are omitted, and a special error property is added.
The type of each report is the same as its outcome’s.
exchange - object
The snapshot of the exchange data that was used during the strategy’s execution. If no exchange data was used, this section is omitted.
- candles - array of objects
  The array of candles that was used during the strategy’s execution. Note that the array includes an aggregate of candles used by all tools and outcomes, even if some of them required fewer candles than this array has. There are no duplicate candles in this array and all of them are ordered in ascending order.
  Candle properties are described in detail here.

Strategy Context #

The context is a special data store that is used to share execution information (such as results included in the report) among the tools and outcomes. This information may be included in various text-based notifications (e.g., Telegram messages) or payloads of custom tools and outcomes.

Properties of tools and outcomes that support context data usage have a context label alongside them.

To access context data, special path-like syntax should be used: {{<tools|outcomes>.<custom-id>.<object>}} (e.g., {{tools.customSMA123.value}}). The first (<tools|outcomes>) and last (<object>) parts of the placeholder are fixed, however, the <custom-id> is determined by the context_id property in the tool or outcome configuration structure. Note that this property is optional and, if not provided, prevents any context data of a tool or outcome from being inserted into the context. This ID must also be unique within its category (either tool or outcome), otherwise its context data may be overwritten. On top of that, it must match the following regexp: ^[a-zA-Z0-9\-_]+$

As mentioned above, the <object> part of the placeholder is fixed and determined by the tool or outcome itself, which in turn means that different tools and outcomes may insert different objects. However, there are a few special objects that are always inserted by all strategies, tools and outcomes:

Objects inserted by strategies (root level):
- symbol - string
  The symbol that was provided when executing a strategy (e.g., {{symbol}}).
Objects inserted by tools:
- permit - boolean
  The object that determines whether a tool gave its permission to continue strategy execution or not. (e.g., {{tools.sma-checker.permit}}).
  This object is rendered unavailable if an error occurs.
- error - string
  The message of the error that occurred during a tool’s execution (e.g., {{tools.sma-checker.error}}).
  This object is rendered unavailable if no error occurs.
Objects inserted by outcomes:
- error - string
  The message of the error that occurred during an outcome’s execution (e.g., {{outcomes.order-placer.error}}).
  This object is rendered unavailable if no error occurs.

Sometimes a certain context value may not be available (e.g., when an error occurs during a tool or outcome’s execution), which means no value is going to be inserted into a context template. An example:

The SMA value is {{tools.sma-with-error.value}}!

Since the context value is not found, this template is transformed into the following text:

The SMA value is !

To avoid such results, a default value may be specified by adding a colon (:) followed by a value that is used only when the context value is not found:

The SMA value is {{tools.sma-with-error.value:not found}}!

The result of the new template:

The SMA value is not found!

Strategy Backtesting #

To check whether a strategy is properly configured, it is worth testing it in an isolated environment that uses historical market data. On top of that, this process (also known as backtesting) may be used to analyse how a certain strategy would behave if it encountered patterns that are similar to those that emerged in the market in the past.

When a strategy is being backtested, outcomes are not executed. Likewise, there are some tools that cannot be tested with data from the past (e.g., the Telegram text analysis tool). Information about backtest support is shown alongside each tool. Note that tools that cannot be backtested automatically return positive results.

{
	"frames": [
		[
			{
				"type": "placeholder",
				"permit": true
			},
			{
				"type": "placeholder",
				"error": "invalid data"
			}
		],
		[
			{
				"type": "placeholder",
				"permit": true
			},
			{
				"type": "placeholder",
				"permit": true
			}
		]
	],
	"exchange": {
		"candles": [
			{
				"opened_at": "2020-09-10T21:00:20Z",
				"open": "2",
				"high": "3",
				"low": "4",
				"close": "5",
				"volume": "6"
			},
			{
				"opened_at": "2020-09-10T21:05:20Z",
				"open": "3",
				"high": "4",
				"low": "5",
				"close": "6",
				"volume": "7"
			}
		]
	}
}

frames - array of arrays
The array of test frames, each containing a sub-array of their tool reports. The frames are ordered in ascending order, which means that the latest frame is always the last one.
Tool report properties are described in detail here.
exchange - object
The snapshot of the exchange data that was used during the strategy’s backtesting process. If no exchange data was used, this section is omitted.
Exchange data properties are described in detail here.