MtApi5: expose MT5 economic calendar (Calendar* functions)

MtApi5/MqlCalendarCountry.cs

@@ -0,0 +1,15 @@
+// ReSharper disable InconsistentNaming
+namespace MtApi5
+{
+    // Country description as returned by the MT5 economic calendar
+    // (native MqlCalendarCountry). See CalendarCountries / CalendarCountryById.
+    public class MqlCalendarCountry
+    {
+        public long id { get; set; }               // Country id (ISO 3166-1)
+        public string name { get; set; } = string.Empty;            // Country text name (in the current terminal encoding)
+        public string code { get; set; } = string.Empty;            // Country code name (ISO 3166-1 alpha-2)
+        public string currency { get; set; } = string.Empty;        // Country currency code
+        public string currency_symbol { get; set; } = string.Empty; // Country currency symbol
+        public string url_name { get; set; } = string.Empty;        // Country name used in the mql5.com website URL
+    }
+}

MtApi5/MqlCalendarEvent.cs

@@ -0,0 +1,22 @@
+// ReSharper disable InconsistentNaming
+namespace MtApi5
+{
+    // Economic calendar event description (native MqlCalendarEvent).
+    // See CalendarEventById / CalendarEventByCountry / CalendarEventByCurrency.
+    public class MqlCalendarEvent
+    {
+        public long id { get; set; }                              // Event id
+        public ENUM_CALENDAR_EVENT_TYPE type { get; set; }        // Event type
+        public ENUM_CALENDAR_EVENT_SECTOR sector { get; set; }    // Sector the event relates to
+        public ENUM_CALENDAR_EVENT_FREQUENCY frequency { get; set; } // Event frequency
+        public ENUM_CALENDAR_EVENT_TIMEMODE time_mode { get; set; }  // Event time mode
+        public long country_id { get; set; }                      // Country id the event relates to
+        public ENUM_CALENDAR_EVENT_UNIT unit { get; set; }        // Measurement unit of the event value
+        public ENUM_CALENDAR_EVENT_IMPORTANCE importance { get; set; } // Event importance
+        public ENUM_CALENDAR_EVENT_MULTIPLIER multiplier { get; set; } // Event value multiplier
+        public int digits { get; set; }                           // Number of decimal places for the value
+        public string source_url { get; set; } = string.Empty;    // URL of the event value source
+        public string event_code { get; set; } = string.Empty;    // Event code
+        public string name { get; set; } = string.Empty;          // Event text name (in the current terminal encoding)
+    }
+}

MtApi5/MqlCalendarValue.cs

@@ -0,0 +1,42 @@
+// ReSharper disable InconsistentNaming
+using System;
+using System.Collections.Generic;
+
+namespace MtApi5
+{
+    // Economic calendar event value (native MqlCalendarValue).
+    // Scaled integer fields (*_value) hold the real value multiplied by 1,000,000;
+    // the sentinel long.MinValue (LONG_MIN) means "no value".
+    // See CalendarValueById / CalendarValueHistory* / CalendarValueLast*.
+    public class MqlCalendarValue
+    {
+        private const long Empty = long.MinValue; // LONG_MIN sentinel = no value
+
+        public long id { get; set; }                  // Value id
+        public long event_id { get; set; }            // Id of the event this value relates to
+        public long mt_time { get; set; }             // Event date/time (original MT time)
+        public long mt_period { get; set; }           // Event reporting period (original MT time)
+        public int revision { get; set; }             // Revision of the published indicator value for the period
+        public long actual_value { get; set; }        // Actual value (x1e6, LONG_MIN if absent)
+        public long prev_value { get; set; }          // Previous value (x1e6, LONG_MIN if absent)
+        public long revised_prev_value { get; set; }  // Revised previous value (x1e6, LONG_MIN if absent)
+        public long forecast_value { get; set; }      // Forecast value (x1e6, LONG_MIN if absent)
+        public ENUM_CALENDAR_EVENT_IMPACT impact_type { get; set; } // Potential impact on the currency rate
+
+        // Convenience accessors (not serialized).
+        public DateTime time => Mt5TimeConverter.ConvertFromMtTime(mt_time);
+        public DateTime period => Mt5TimeConverter.ConvertFromMtTime(mt_period);
+        public double? ActualValue      => actual_value       == Empty ? (double?)null : actual_value       / 1e6;
+        public double? PrevValue        => prev_value         == Empty ? (double?)null : prev_value         / 1e6;
+        public double? RevisedPrevValue => revised_prev_value == Empty ? (double?)null : revised_prev_value / 1e6;
+        public double? ForecastValue    => forecast_value     == Empty ? (double?)null : forecast_value     / 1e6;
+    }
+
+    // Wraps the in/out change_id together with the values array returned by
+    // CalendarValueLast / CalendarValueLastByEvent.
+    internal class CalendarValueLastResult
+    {
+        public long ChangeId { get; set; }
+        public List<MqlCalendarValue> Values { get; set; } = new();
+    }
+}

MtApi5/Mt5Enums.cs

@@ -951,4 +951,92 @@ public enum ENUM_DATATYPE
         TYPE_STRING     = 14
     }
     #endregion
+
+    #region Economic Calendar Enums
+
+    public enum ENUM_CALENDAR_EVENT_TYPE
+    {
+        CALENDAR_TYPE_EVENT     = 0,
+        CALENDAR_TYPE_INDICATOR = 1,
+        CALENDAR_TYPE_HOLIDAY   = 2
+    }
+
+    public enum ENUM_CALENDAR_EVENT_SECTOR
+    {
+        CALENDAR_SECTOR_NONE       = 0,
+        CALENDAR_SECTOR_MARKET     = 1,
+        CALENDAR_SECTOR_GDP        = 2,
+        CALENDAR_SECTOR_JOBS       = 3,
+        CALENDAR_SECTOR_PRICES     = 4,
+        CALENDAR_SECTOR_MONEY      = 5,
+        CALENDAR_SECTOR_TRADE      = 6,
+        CALENDAR_SECTOR_GOVERNMENT = 7,
+        CALENDAR_SECTOR_BUSINESS   = 8,
+        CALENDAR_SECTOR_CONSUMER   = 9,
+        CALENDAR_SECTOR_HOUSING    = 10,
+        CALENDAR_SECTOR_TAXES      = 11,
+        CALENDAR_SECTOR_HOLIDAYS   = 12
+    }
+
+    public enum ENUM_CALENDAR_EVENT_FREQUENCY
+    {
+        CALENDAR_FREQUENCY_NONE    = 0,
+        CALENDAR_FREQUENCY_WEEK    = 1,
+        CALENDAR_FREQUENCY_MONTH   = 2,
+        CALENDAR_FREQUENCY_QUARTER = 3,
+        CALENDAR_FREQUENCY_YEAR    = 4,
+        CALENDAR_FREQUENCY_DAY     = 5
+    }
+
+    public enum ENUM_CALENDAR_EVENT_TIMEMODE
+    {
+        CALENDAR_TIMEMODE_DATETIME  = 0,
+        CALENDAR_TIMEMODE_DATE      = 1,
+        CALENDAR_TIMEMODE_NOTIME    = 2,
+        CALENDAR_TIMEMODE_TENTATIVE = 3
+    }
+
+    public enum ENUM_CALENDAR_EVENT_UNIT
+    {
+        CALENDAR_UNIT_NONE      = 0,
+        CALENDAR_UNIT_PERCENT   = 1,
+        CALENDAR_UNIT_CURRENCY  = 2,
+        CALENDAR_UNIT_HOUR      = 3,
+        CALENDAR_UNIT_JOB       = 4,
+        CALENDAR_UNIT_RIG       = 5,
+        CALENDAR_UNIT_USD       = 6,
+        CALENDAR_UNIT_PEOPLE    = 7,
+        CALENDAR_UNIT_MORTGAGE  = 8,
+        CALENDAR_UNIT_VOTE      = 9,
+        CALENDAR_UNIT_BARREL    = 10,
+        CALENDAR_UNIT_CUBICFEET = 11,
+        CALENDAR_UNIT_POSITION  = 12,
+        CALENDAR_UNIT_BUILDING  = 13
+    }
+
+    public enum ENUM_CALENDAR_EVENT_IMPORTANCE
+    {
+        CALENDAR_IMPORTANCE_NONE     = 0,
+        CALENDAR_IMPORTANCE_LOW      = 1,
+        CALENDAR_IMPORTANCE_MODERATE = 2,
+        CALENDAR_IMPORTANCE_HIGH     = 3
+    }
+
+    public enum ENUM_CALENDAR_EVENT_MULTIPLIER
+    {
+        CALENDAR_MULTIPLIER_NONE      = 0,
+        CALENDAR_MULTIPLIER_THOUSANDS = 1,
+        CALENDAR_MULTIPLIER_MILLIONS  = 2,
+        CALENDAR_MULTIPLIER_BILLIONS  = 3,
+        CALENDAR_MULTIPLIER_TRILLIONS = 4
+    }
+
+    public enum ENUM_CALENDAR_EVENT_IMPACT
+    {
+        CALENDAR_IMPACT_NA       = 0,
+        CALENDAR_IMPACT_POSITIVE = 1,
+        CALENDAR_IMPACT_NEGATIVE = 2
+    }
+
+    #endregion
 }

MtApi5/MtApi5Client.cs

@@ -1049,6 +1049,160 @@ public int CopyRates(string symbolName, ENUM_TIMEFRAMES timeframe, DateTime star
             return response?.Count ?? 0;
         }
 
+        #region Economic Calendar
+
+        ///<summary>
+        ///Gets the array of country descriptions available in the terminal's economic calendar.
+        ///</summary>
+        ///<returns>Array of countries (empty if none).</returns>
+        public MqlCalendarCountry[] CalendarCountries()
+        {
+            // Send an empty object "{}" (not null): the EA's GET_JSON_PAYLOAD needs a valid JSON object.
+            var cmdParams = new Dictionary<string, object>();
+            var response = SendCommand<List<MqlCalendarCountry>>(ExecutorHandle, Mt5CommandType.CalendarCountries, cmdParams);
+            return response?.ToArray() ?? [];
+        }
+
+        ///<summary>
+        ///Gets a country description by its id.
+        ///</summary>
+        ///<param name="countryId">Country id (ISO 3166-1).</param>
+        ///<param name="country">Receives the country description when found.</param>
+        ///<returns>true if the country was found; otherwise false.</returns>
+        public bool CalendarCountryById(long countryId, out MqlCalendarCountry? country)
+        {
+            var cmdParams = new Dictionary<string, object> { { "CountryId", countryId } };
+            country = SendCommand<MqlCalendarCountry>(ExecutorHandle, Mt5CommandType.CalendarCountryById, cmdParams);
+            return country != null;
+        }
+
+        ///<summary>
+        ///Gets an economic calendar event description by its id.
+        ///</summary>
+        ///<param name="eventId">Event id.</param>
+        ///<param name="evt">Receives the event description when found.</param>
+        ///<returns>true if the event was found; otherwise false.</returns>
+        public bool CalendarEventById(long eventId, out MqlCalendarEvent? evt)
+        {
+            var cmdParams = new Dictionary<string, object> { { "EventId", eventId } };
+            evt = SendCommand<MqlCalendarEvent>(ExecutorHandle, Mt5CommandType.CalendarEventById, cmdParams);
+            return evt != null;
+        }
+
+        ///<summary>
+        ///Gets the array of calendar events for the specified country.
+        ///</summary>
+        ///<param name="countryCode">Country code name (ISO 3166-1 alpha-2), e.g. "US".</param>
+        ///<returns>Array of events (empty if none).</returns>
+        public MqlCalendarEvent[] CalendarEventByCountry(string countryCode)
+        {
+            var cmdParams = new Dictionary<string, object> { { "CountryCode", countryCode ?? string.Empty } };
+            var response = SendCommand<List<MqlCalendarEvent>>(ExecutorHandle, Mt5CommandType.CalendarEventByCountry, cmdParams);
+            return response?.ToArray() ?? [];
+        }
+
+        ///<summary>
+        ///Gets the array of calendar events for the specified currency.
+        ///</summary>
+        ///<param name="currency">Currency code, e.g. "USD".</param>
+        ///<returns>Array of events (empty if none).</returns>
+        public MqlCalendarEvent[] CalendarEventByCurrency(string currency)
+        {
+            var cmdParams = new Dictionary<string, object> { { "Currency", currency ?? string.Empty } };
+            var response = SendCommand<List<MqlCalendarEvent>>(ExecutorHandle, Mt5CommandType.CalendarEventByCurrency, cmdParams);
+            return response?.ToArray() ?? [];
+        }
+
+        ///<summary>
+        ///Gets a calendar event value by its id.
+        ///</summary>
+        ///<param name="valueId">Value id.</param>
+        ///<param name="value">Receives the event value when found.</param>
+        ///<returns>true if the value was found; otherwise false.</returns>
+        public bool CalendarValueById(long valueId, out MqlCalendarValue? value)
+        {
+            var cmdParams = new Dictionary<string, object> { { "ValueId", valueId } };
+            value = SendCommand<MqlCalendarValue>(ExecutorHandle, Mt5CommandType.CalendarValueById, cmdParams);
+            return value != null;
+        }
+
+        ///<summary>
+        ///Gets calendar event values by event id within the specified date range.
+        ///</summary>
+        ///<param name="eventId">Event id.</param>
+        ///<param name="from">Range start (left boundary).</param>
+        ///<param name="to">Range end (right boundary). Pass default for an open-ended range.</param>
+        ///<returns>Array of event values (empty if none).</returns>
+        public MqlCalendarValue[] CalendarValueHistoryByEvent(long eventId, DateTime from, DateTime to = default)
+        {
+            var cmdParams = new Dictionary<string, object>
+            {
+                { "EventId", eventId },
+                { "FromDate", Mt5TimeConverter.ConvertToMtTime(from) },
+                { "ToDate", to == default ? 0 : Mt5TimeConverter.ConvertToMtTime(to) }
+            };
+            var response = SendCommand<List<MqlCalendarValue>>(ExecutorHandle, Mt5CommandType.CalendarValueHistoryByEvent, cmdParams);
+            return response?.ToArray() ?? [];
+        }
+
+        ///<summary>
+        ///Gets calendar event values within the specified date range, optionally filtered by country and/or currency.
+        ///</summary>
+        ///<param name="from">Range start (left boundary).</param>
+        ///<param name="to">Range end (right boundary). Pass default for an open-ended range.</param>
+        ///<param name="countryCode">Optional country code filter (ISO 3166-1 alpha-2). null/empty = no filter.</param>
+        ///<param name="currency">Optional currency filter. null/empty = no filter.</param>
+        ///<returns>Array of event values (empty if none).</returns>
+        public MqlCalendarValue[] CalendarValueHistory(DateTime from, DateTime to = default,
+                                                       string? countryCode = null, string? currency = null)
+        {
+            var cmdParams = new Dictionary<string, object>
+            {
+                { "FromDate", Mt5TimeConverter.ConvertToMtTime(from) },
+                { "ToDate", to == default ? 0 : Mt5TimeConverter.ConvertToMtTime(to) },
+                { "CountryCode", countryCode ?? string.Empty },
+                { "Currency", currency ?? string.Empty }
+            };
+            var response = SendCommand<List<MqlCalendarValue>>(ExecutorHandle, Mt5CommandType.CalendarValueHistory, cmdParams);
+            return response?.ToArray() ?? [];
+        }
+
+        ///<summary>
+        ///Gets the calendar event values that changed for the specified event since the given change id.
+        ///</summary>
+        ///<param name="eventId">Event id.</param>
+        ///<param name="changeId">In/out change id: pass the last known value (0 initially); receives the current change id.</param>
+        ///<returns>Array of changed event values (empty if none).</returns>
+        public MqlCalendarValue[] CalendarValueLastByEvent(long eventId, ref long changeId)
+        {
+            var cmdParams = new Dictionary<string, object> { { "EventId", eventId }, { "ChangeId", changeId } };
+            var response = SendCommand<CalendarValueLastResult>(ExecutorHandle, Mt5CommandType.CalendarValueLastByEvent, cmdParams);
+            changeId = response?.ChangeId ?? changeId;
+            return response?.Values?.ToArray() ?? [];
+        }
+
+        ///<summary>
+        ///Gets the calendar event values that changed since the given change id, optionally filtered by country and/or currency.
+        ///</summary>
+        ///<param name="changeId">In/out change id: pass the last known value (0 initially); receives the current change id.</param>
+        ///<param name="countryCode">Optional country code filter (ISO 3166-1 alpha-2). null/empty = no filter.</param>
+        ///<param name="currency">Optional currency filter. null/empty = no filter.</param>
+        ///<returns>Array of changed event values (empty if none).</returns>
+        public MqlCalendarValue[] CalendarValueLast(ref long changeId, string? countryCode = null, string? currency = null)
+        {
+            var cmdParams = new Dictionary<string, object>
+            {
+                { "ChangeId", changeId },
+                { "CountryCode", countryCode ?? string.Empty },
+                { "Currency", currency ?? string.Empty }
+            };
+            var response = SendCommand<CalendarValueLastResult>(ExecutorHandle, Mt5CommandType.CalendarValueLast, cmdParams);
+            changeId = response?.ChangeId ?? changeId;
+            return response?.Values?.ToArray() ?? [];
+        }
+
+        #endregion
+
         ///<summary>
         ///The function gets to time_array history data of bar opening time for the specified symbol-period pair in the specified quantity. It should be noted that elements ordering is from present to past, i.e., starting position of 0 means the current bar.
         ///</summary>

MtApi5/MtProtocol/Mt5CommandType.cs

@@ -260,6 +260,17 @@ internal enum Mt5CommandType
         OrderCheck = 303,
         Buy = 304,
         Sell = 305,
-        GetSymbols = 306
+        GetSymbols = 306,
+
+        CalendarCountries = 307,
+        CalendarCountryById = 308,
+        CalendarEventById = 309,
+        CalendarEventByCountry = 310,
+        CalendarEventByCurrency = 311,
+        CalendarValueById = 312,
+        CalendarValueHistoryByEvent = 313,
+        CalendarValueHistory = 314,
+        CalendarValueLastByEvent = 315,
+        CalendarValueLast = 316
     }
 }

TestClients/MtApi5TestClient/MainWindow.xaml

@@ -421,6 +421,8 @@
                             <WrapPanel Grid.Row="1" Grid.Column="0" Margin="5">
                                 <Button Command="{Binding CopyRatesCommand}" Margin="1"
                                         Content="CopyRates" HorizontalAlignment="Left" />
+                                <Button Command="{Binding CalendarHistoryCommand}" Margin="1"
+                                        Content="CalendarHistory" HorizontalAlignment="Left" />
                                 <Button Command="{Binding CopyTimesCommand}" Margin="1"
                                         Content="CopyTimes" HorizontalAlignment="Left" />
                                 <Button Command="{Binding CopyOpenCommand}" Margin="1"