Skip to content

Read historical candles (OHLCV)#

About#

Returns historical candles for a specific symbol and timeframe from a MetaTrader account

GET /users/current/accounts/:accountId/historical-market-data/symbols/:symbol/timeframes/:timeframe/candles

Note: this API is hosted on a different hostname than other MetaApi APIs. Please check the code example below.

Note: this API might require MT terminal to download and process much data at once causing delays in request execution which may be greater than default timeout of 4 minutes.

Note: there is a bug in MT5 terminal which causes the terminal to hang in infinite cycle is candles are requested for a symbol with missing market data which causes the API to stop reaponding to the requests. A workaround is to redeploy your account.

For more information see Swagger documentation. Note, that this URL is valid for new-york region only. You can find URLs for other regions on API access page.

Headers#

Name Type Required Description
auth-token string Yes authorization token. See Authentication & authorization

Path parameters#

Name Type Required Description
accountId string Yes MetaTrader account id. You can retrieve account id from Web application after you add your MetaTrader account to our platform. The account id can also be obtained via Provisioning API
symbol string Yes symbol to retrieve historical candles for (e.g. a currency pair or an index)
timeframe string Yes defines the timeframe according to which the candles must be generated. Allowed values for MT5 are 1m, 2m, 3m, 4m, 5m, 6m, 10m, 12m, 15m, 20m, 30m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 1d, 1w, 1mn. Allowed values for MT4 are 1m, 5m, 15m 30m, 1h, 4h, 1d, 1w, 1mn

Query parameters#

Name Type Required Description
startTime datetime time to start loading candles from. Note that candles are loaded in backwards direction, so this should be the latest time. Leave empty to request latest candles.
limit integer maximum number of candles to retrieve. Must be less or equal to 1000

Responses:

  • 200 - Historical candles for a specified symbol, timeframe and MetaTrader account returned successfully. Response schema: array<MetatraderCandle>
  • 401 - Authorization failed. Response schema: Error
  • 404 - MetaTrader account not found or not provisioned yet or symbol is not defined for this broker. Response schema: Error

Examples#

Example request:

curl -X GET --header 'Accept: application/json' --header 'auth-token: token' 'https://mt-market-data-client-api-v1.new-york.agiliumtrade.ai/users/current/accounts/865d3a4d-3803-486d-bdf3-a85679d9fad2/historical-market-data/symbols/AUDNZD/timeframes/15m/candles?startTime=2020-04-07T03:45:00.000Z&limit=1'

Example response:

[{
  "symbol": "AUDNZD",
  "timeframe": "15m",
  "time": "2020-04-07T03:45:00.000Z",
  "brokerTime": "2020-04-07 06:45:00.000",
  "open": 1.03297,
  "high": 1.06309,
  "low": 1.02705,
  "close": 1.043,
  "tickVolume": 1435,
  "spread": 17,
  "volume": 345
}]