3.2Historic candle data

This section describes how to request candle data from the framework. There is a separate section below about features to help you work with that candle data: storing it, adding technical analysis calculations etc.

You can request chart/candle data using Framework.RequestCandles(). The RequestCandles() function takes two parameters:

Parameter	Description
requestDef	Details of the candle request: market, timeframe etc
callback	Callback function which asynchronously receives the requested data (and then further updates depending on the type of request)

For example:

// Request latest candles on EUR/USD H1 (a default number of candles filled in by the framework)

Framework.RequestCandles({

instrumentId: "EUR/USD",

timeframe: 3600

}, function (MsgCandles) {

// Function which asynchronously receives the candle data from the framework

});

There are three types of candle request:

The most common: a request for the last N candles up to the current time, e.g. in order to display a trading chart.

A request for the N candles up to a historic point in time, e.g. in order to add further history when a user scrolls back in time on a chart

A request for the candles between start and end dates.

All requests must include an instrumentId and a timeframe (as in the above example). These are the only compulsory properties in a request.

The list of available timeframes depends on the account and trading back-end which MyTrader is connected to. This information is provided in the account features.

A request for N candles (up to the current time or a specific historic date) can include a count property specifying how many candles you want. However, we recommend that you omit this unless absolutely necessary, and let the framework pick a value for you. The cost of collecting candle data can vary based on the back-end system. If you omit count, the framework has discretion to make a smaller or larger request depending on how quickly the back-end system processes requests. As a general rule, count should not exceed 1000. If you need more candles than this, request them in separate batches (going backwards in time as each batch is received).

You can specify a start date and/or end date for the candle request using startDate and endDate.

If you make a request for candles up to the current time then, by default, the request will stream: your callback function will get an initial call with the existing candle data, and will then get further calls on each change in the market price - updating the current candle or adding a new candle. If you don't require streaming, you can turn it off by specifying noStreaming:true.

In full, the possible properties of a candle request are therefore as follows:

Property	Type	Description
instrumentId	Text	ID of the FXB.Instrument for which you want data
timeframe	Integer (timeframe)	Chart timeframe, such as 3600 for H1
count	Integer	Number of candles (not applicable if startDate is provided)
startDate	Integer (millisecond time value)	Start date for historic request. If provided, must also set endDate.
endDate	Integer (millisecond time value)	End date for historic request
noStreaming	Boolean	Optional flag which can be used to turn off streaming on requests. (Automatic if a request has an endDate.)
requestId	Text	Optional ID for the request, repeated back in messages to the callback function. If not provided, the framework will allocate one automatically. If you want to allocate your own ID, you are recommended to use FXB.utils.GenerateGuid().
timezone	Time zone	Optional time zone settings for the request. See below.
convertTimes	Boolean	Option to do conversion of UTC times before returning the data. See below.

Note: the Promise version of the function, pRequestCandles(), always sets noStreaming:true because a Promise cannot settle more than once; it cannot receive multiple callbacks with streaming data.