Tectonic Structure Engine

Библиотека MQL4, которая строит рыночную структуру для вашего советника, индикатора или скрипта: подтвержденные свинги с метками HH, HL, LH, LL, EQH и EQL, слом структуры (BOS), смена характера (CHoCH), снятие ликвидности, ордер-блоки и fair value gap с отслеживанием заполнения, а также положение цены в торговом диапазоне. Читает только закрытые бары и никогда не перерисовывает. Не торгует, не рисует и не выдает алертов. Вы получаете скомпилированный Tectonic_Structure_Engine.ex4; эта страница является полным справочником API.

Быстрый старт

1. Скопируйте Tectonic_Structure_Engine.ex4 в MQL4/Libraries (Файл > Открыть каталог данных).
2. Вставьте блок #import ниже в свою программу.
3. В OnInit: h = TSE_Create("", 0, 3, 1000); при желании TSE_Configure.
4. Вызывайте TSE_Update(h) в OnTick или OnCalculate. Без нового бара функция возвращает 0 примерно за микросекунду.
5. Читайте TSE_Trend, TSE_GetEvent, TSE_NearestZone и другие; TSE_Release(h) в OnDeinit.
6. Проверка: запустите пример ниже в тестере стратегий (любой символ, M15). Журнал выводит каждое событие; первое обновление выводит всю историю.

Объявление импорта (готово к копированию)

#import "Tectonic_Structure_Engine.ex4"
   int    TSE_Create(string symbol, int timeframe, int strength, int history_bars);
   bool   TSE_Configure(int handle, int break_mode, double min_swing_atr, double equal_tol_atr, double fvg_min_atr, int atr_period);
   void   TSE_Release(int handle);
   int    TSE_Update(int handle);
   int    TSE_Trend(int handle);
   int    TSE_SwingCount(int handle);
   bool   TSE_GetSwing(int handle, int index, int &side, double &price, datetime &time, int &label);
   int    TSE_EventCount(int handle);
   bool   TSE_GetEvent(int handle, int index, int &type, double &level, datetime &swing_time, datetime &break_time);
   bool   TSE_GetLevels(int handle, double &swing_high, double &swing_low, bool &high_broken, bool &low_broken);
   double TSE_RangePosition(int handle, double price);
   int    TSE_ZoneCount(int handle);
   bool   TSE_GetZone(int handle, int index, int &kind, int &dir, double &top, double &bottom, datetime &time, int &state, double &fill);
   int    TSE_NearestZone(int handle, int kind, int dir, double price, double &top, double &bottom);
   int    TSE_GetStats(int handle, int &stats[]);
   int    TSE_LastError();
   string TSE_ErrorText(int code);
   string TSE_LabelText(int label);
   string TSE_EventText(int type);
   string TSE_ZoneText(int kind, int dir);
   string TSE_StateText(int state);
#import 

Коды

• Метки свингов: 1 HH, 2 LH, 3 EQH (максимумы); -1 LL, -2 HL, -3 EQL (минимумы); 0 FIRST (на этой стороне еще не было свинга).
• Типы событий: 1 BOS UP, -1 BOS DOWN, 2 CHOCH UP, -2 CHOCH DOWN, 3 SWEEP HIGH, -3 SWEEP LOW.
• Вид зоны (kind): 1 fair value gap, 2 ордер-блок. dir: 1 бычья (поддержка), -1 медвежья (сопротивление). Тексты: BULL FVG, BEAR FVG, BULL OB, BEAR OB.
• Состояние зоны: 0 FRESH (не тронута), 1 TESTED (цена зашла), 2 FILLED (FVG пройден насквозь), 3 BROKEN (OB пробит закрытием).
• Ошибки: 0 OK, -1 BAD HANDLE, -2 BAD PARAMETERS, -3 NO HISTORY, -4 NO FREE SLOT, -5 BAD INDEX. Для других кодов текстовые функции возвращают UNKNOWN.

Как читается каждый закрытый бар

1. Зоны: минимум внутри бычьей зоны (максимум внутри медвежьей) ставит TESTED и увеличивает fill, глубину самого сильного захода в % от высоты зоны. FVG становится FILLED, когда цена доходит до дальней границы; OB становится BROKEN при закрытии за дальней границей (fill может достигнуть 100%, пока OB активен).
2. Свинги: бар, отстоящий на strength баров назад, считается свинг-максимумом, если его максимум выше strength баров до него и не ниже strength баров после него (минимумы зеркально). Свинг сообщается с опозданием на strength баров и никогда не смещается. При min_swing_atr больше 0 максимум минус самый низкий минимум из 2 x strength + 1 баров должен быть не меньше min_swing_atr x ATR. Метка относительно предыдущего свинга той же стороны: в пределах equal_tol_atr x ATR это EQH или EQL, иначе HH или LH, LL или HL. Последние свинг-максимум и свинг-минимум являются уровнями слома.
3. Сломы: break_mode 0 требует закрытия за уровнем, 1 достаточно тени. Слом свинг-максимума дает CHOCH UP, если тренд был -1, иначе BOS UP; тренд становится 1, уровень израсходован. Минимумы зеркально. В режиме закрытия тень за уровнем с закрытием обратно внутри является SWEEP, один раз на уровень.
4. Ордер-блок: при каждом BOS или CHoCH последняя противоположная свеча (медвежья для слома вверх) на экстремуме отрезка между свингом и сломом или до 10 баров раньше; зона равна ее диапазону от максимума до минимума.
5. Fair value gap: минимум третьей свечи выше максимума первой (бычий) или максимум третьей ниже минимума первой (медвежий), высотой не меньше fvg_min_atr x ATR.

ATR это простое среднее истинного диапазона за atr_period баров.

Справочник API

TSE_Create

symbol: "" или NULL = символ графика; символ должен существовать. timeframe: 0 = период графика, иначе от PERIOD_M1 до PERIOD_MN1. strength: 1-50. history_bars: 100-20000, строятся при первом обновлении. Возвращает handle 0-31 или -1 с BAD PARAMETERS или NO FREE SLOT. По умолчанию: break_mode 0, min_swing_atr 0, equal_tol_atr 0.10, fvg_min_atr 0.25, atr_period 14.

TSE_Configure

break_mode 0-1, min_swing_atr 0-10 (0 = выключено), equal_tol_atr 0-5, fvg_min_atr 0-10, atr_period 1-500. Очищает handle; следующий TSE_Update строит заново. Любое значение вне диапазона: false, BAD PARAMETERS, ничего не меняется.

TSE_Release

Освобождает handle для повторного использования. Вызывайте в OnDeinit.

TSE_Update

Читает еще не обработанные закрытые бары; первый вызов строит history_bars. Возвращает число новых событий (индексы от 0 до n-1 в TSE_GetEvent), 0 без нового бара или -1: BAD HANDLE либо NO HISTORY, пока загружено меньше 2 x strength + 4 баров (вызовите снова на следующем тике). Если последний прочитанный бар исчез (история перезагружена), handle перестраивается сам.

int n = TSE_Update(h);
if(n > 0) Print(n, " new events"); 

TSE_Trend

1 после слома вверх, -1 после слома вниз, 0 до первого слома или для неверного handle.

TSE_SwingCount и TSE_GetSwing

Сохраненные свинги, самый новый с индексом 0: side (1 максимум, -1 минимум), price, время бара свинга, label. Количество равно -1 для неверного handle; вне диапазона от 0 до количество-1 TSE_GetSwing возвращает false с BAD INDEX.

TSE_EventCount и TSE_GetEvent

Сохраненные события, самое новое с индексом 0: type, level (цена свинга), swing_time, break_time (бар, который пробил или снял уровень).

TSE_GetLevels

Последние свинг-максимум и свинг-минимум (0.0, если их еще нет) и признак, пробит ли каждый. Непробитый уровень является следующим триггером BOS или CHoCH.

TSE_RangePosition

Положение цены между этими двумя уровнями: 0 = свинг-минимум, 50 = равновесие, 100 = свинг-максимум, ниже 0 или выше 100 за пределами диапазона. price 0 = Bid символа handle. EMPTY_VALUE, если уровня нет или максимум не выше минимума. Демо показывает DISCOUNT ниже 45 и PREMIUM выше 55.

TSE_ZoneCount и TSE_GetZone

Сохраненные зоны во всех состояниях, самая новая с индексом 0: kind, dir, top, bottom, time (FVG: средняя свеча; OB: сама свеча), state, fill 0-100.

TSE_NearestZone

Ближайшая к цене зона FRESH или TESTED (0 = Bid); внутри зоны расстояние 0, при равенстве выбирается более новая. kind: 0 любая, 1 FVG, 2 OB. dir: 0 любая, 1, -1. Возвращает ее индекс для TSE_GetZone и заполняет top и bottom; -1, если зон нет (ошибка OK), или BAD PARAMETERS.

double top, bottom;
int z = TSE_NearestZone(h, 2, 1, 0, top, bottom);   // nearest bullish order block 

TSE_GetStats

Передайте динамический массив int; его размер станет 12, функция вернет 12: 0 прочитано баров, 1 свинг-максимумы, 2 свинг-минимумы, 3 BOS UP, 4 BOS DOWN, 5 CHOCH UP, 6 CHOCH DOWN, 7 SWEEP HIGH, 8 SWEEP LOW, 9 FVG, 10 OB, 11 активные сейчас зоны. Счетчики с последнего построения.

TSE_LastError и текстовые функции

TSE_LastError: код последнего вызова. TSE_ErrorText, TSE_LabelText, TSE_EventText, TSE_ZoneText(kind, dir) и TSE_StateText возвращают строки из раздела Коды.

Рабочий пример интеграции

#import "Tectonic_Structure_Engine.ex4"
   int    TSE_Create(string symbol, int timeframe, int strength, int history_bars);
   void   TSE_Release(int handle);
   int    TSE_Update(int handle);
   int    TSE_Trend(int handle);
   bool   TSE_GetEvent(int handle, int index, int &type, double &level, datetime &swing_time, datetime &break_time);
   int    TSE_NearestZone(int handle, int kind, int dir, double price, double &top, double &bottom);
   string TSE_EventText(int type);
#import

int h = -1, htf = -1;

int OnInit()
{
   h   = TSE_Create("", 0, 3, 1000);           // chart timeframe
   htf = TSE_Create("", PERIOD_H4, 3, 1000);   // higher-timeframe bias
   return (h >= 0 && htf >= 0) ? INIT_SUCCEEDED : INIT_FAILED;
}

void OnDeinit(const int reason) { TSE_Release(h); TSE_Release(htf); }

void OnTick()
{
   TSE_Update(htf);
   int n = TSE_Update(h);
   for(int i = n - 1; i >= 0; i--)
   {
      int type; double level; datetime st, bt;
      if(TSE_GetEvent(h, i, type, level, st, bt))
         Print(TSE_EventText(type), " at ", level, ", H4 trend ", TSE_Trend(htf));
   }
   double top, bottom;
   if(n > 0 && TSE_NearestZone(h, 2, 1, 0, top, bottom) >= 0)
      Print("nearest bullish OB ", bottom, " - ", top);
} 

Типичные настройки

• Внутренняя и внешняя структура: два handle на одном графике, strength 2 и 8.
• Мультитаймфреймовый уклон: handle графика для входов, handle H4 или D1 как фильтр TSE_Trend.
• Сломы по тени: TSE_Configure(h, 1, 0, 0.10, 0.25, 14); в этом режиме снятий нет.
• Меньше и крупнее зоны и свинги: fvg_min_atr 0.5-1.0, min_swing_atr 1.0.

Архитектура и примечания

• Один движок на handle, до 32 handle на программу; у каждой импортирующей программы свои. Данные хранятся в памяти и после перезапуска строятся заново из истории.
• Только закрытые бары, каждый читается один раз, от старых к новым: ничего не перерисовывается, бар 0 не используется.
• Построение 20 000 баров заняло около 80 мс в тестере стратегий MT4.
• Другие символы и таймфреймы читаются через iHigh, iLow, iOpen, iClose и iTime; NO HISTORY нормально, пока терминал их загружает. В тестере стратегий используйте тестируемый символ (любой таймфрейм).
• На handle: до 2000 свингов, 2000 событий и 500 зон; при заполнении отбрасываются самые старые 10%.
• MetaTrader 4 build 600 или новее. Безопасна в тестере стратегий и при оптимизации. Без DLL, файлов, глобальных переменных, графических объектов, таймеров, алертов и торговли.

Предупреждение о рисках

Библиотека описывает структуру цены. Она не прогнозирует цены и не гарантирует прибыль. Сначала проверяйте любую стратегию на ее основе на демо-счете.