Português PT
Ver no GitHub

Estratégia Mínima de Frank Ud

Este exemplo transporta o consultor especialista clássico Frank Ud MetaTrader para StockSharp usando a estratégia de alto nível API. O script MQL original executa uma grade martingale protegida que continua adicionando posições sempre que o preço se move em relação à entrada mais recente. Os lucros são bloqueados quando a ordem mais recente (e, portanto, maior) ganha um número fixo de pips, após o qual todas as negociações desse lado são fechadas simultaneamente.

Lógica central

  1. Hedge simétrico. A estratégia mantém duas escadas independentes de posições de mercado: uma escada longa e uma escada curta. Portanto, é possível manter posições longas e curtas ao mesmo tempo, como no modo de hedge de MetaTrader.
  2. Martingale progressão. A primeira ordem de qualquer lado usa InitialVolume (padrão 0,1 lote). Cada entrada subsequente no mesmo lado duplica o maior volume atualmente aberto. Todo lote que a estratégia envia — inclusive o primeiro — é então ajustado ao que o instrumento realmente aceita: arredondado para baixo até um número inteiro de unidades de VolumeStep, elevado a MinVolume se ficar abaixo dele e limitado a MaxVolume. As restrições que o instrumento não informa são ignoradas.
  3. Espaçamento de entrada. Uma nova posição é adicionada somente quando o preço se moveu pelo menos ReEntryPips (padrão 41 pips) além do melhor preço de entrada da escada existente. A escada longa espera que os preços de venda caiam abaixo de lowest_buy - ReEntryPips, enquanto a escada curta espera que os preços de compra subam acima de highest_sell + ReEntryPips. Ambos os lados da cotação vêm do fechamento da mesma vela, de modo que nesta portabilidade as duas comparações são feitas contra o mesmo preço.
  4. Coleta de lucros. Para cada escada, a negociação com o maior volume atua como a ordem de "gatilho". Quando seu lucro excede TakeProfitPips (padrão 65 pips), ou quando o preço atinge o alvo com folga situado a TakeProfitPips + ExtraTakeProfitPips pips dessa entrada, cada posição desse lado é achatada com uma única ordem de mercado e a escada é esvaziada.
  5. Proteção de margem. Antes de enviar uma nova entrada, a estratégia verifica se a margem livre da carteira — seu valor atual menos a comissão que ela informa — permanece acima de Balance × MinimumFreeMarginRatio (padrão 0,5). A proteção vale para as duas escadas e para cada entrada delas, inclusive a primeira. Definir a proporção como zero a desativa, e o mesmo acontece se a carteira não devolver valor algum: em ambos os casos a verificação simplesmente passa e a estratégia volta ao comportamento de volume fixo do especialista original.

Parâmetros

Parâmetro Descrição
TakeProfitPips Limite de lucro do pip medido no maior e mais recente pedido. Uma vez ultrapassado, todas as posições desse lado serão fechadas.
ReEntryPips Distância mínima de pip entre a melhor entrada existente e a oferta/venda atual antes de uma nova ordem de martingale ser adicionada.
InitialVolume Tamanho base do lote para a primeira ordem de cada escada. Os pedidos subsequentes dobram o maior volume ativo.
MinimumFreeMarginRatio Proporção necessária entre margem livre e saldo antes que novas entradas sejam permitidas. Defina como 0 para desativar a verificação. Padrão 0,5.
ExtraTakeProfitPips Distância adicional em pips somada a TakeProfitPips no cálculo do alvo de saída com folga. Padrão 25.
CandleType Série de velas que a estratégia assina. Padrão: período de 1 minuto.

Notas de implementação

  • Um pip não é o passo de preço bruto. Na primeira vela fechada que processa, a estratégia define um pip como um décimo de milésimo do preço cotado, limita-o inferiormente ao passo de preço do instrumento (para que nunca seja mais fino do que o instrumento realmente negocia) e mantém esse valor pelo resto da execução, de modo que a grade não se desloque sob si mesma. Isso reproduz a convenção do forex para a qual o especialista foi escrito (0,0001 no EURUSD a 1,10; 0,01 no USDJPY a 150) e mantém as distâncias significativas em um instrumento cotado com cinco algarismos, onde o passo bruto de 0,01 atingiria um alvo de 65 pips em quase toda vela. Se o instrumento não informar um passo de preço, o pip é definido apenas por essa fração.
  • A estratégia é conduzida por velas fechadas, e não por cotações de nível 1. Ela assina a série CandleType (por padrão, um período de 1 minuto) e ignora toda vela que ainda não esteja fechada. O histórico incluído não traz livro de ofertas, portanto o fechamento da vela fechada serve tanto como preço de compra quanto como preço de venda. As implementações em C# e em Python assinam exatamente da mesma forma.
  • A entrada na escada é registrada no momento em que a ordem é enviada, e não quando ela é executada: na abertura, o fechamento da vela e o volume solicitado são acrescentados à lista; no fechamento, uma única ordem de mercado pelo volume total da escada é enviada e a lista é esvaziada. Nenhum dicionário de intenções de ordem é mantido e nenhum retorno de chamada de execução é usado — neste emulador a execução chega de forma síncrona dentro do registro da ordem, antes mesmo que a ordem pudesse ser escrita em tal dicionário.
  • A contabilidade de posição armazena cada entrada da escada (preço e volume) em listas simples em vez de consultar estatísticas cumulativas, preservando o comportamento das matrizes MQL que foram usadas para localizar o maior lote e seu preço de entrada.
  • O buffer extra em pips que o especialista original colocou em cada ordem de realização de lucro é exposto como o parâmetro ExtraTakeProfitPips (25 pips por padrão) e retido como uma condição de saída adicional.

As implementações estão disponíveis em C# e Python.

using System;
using System.Linq;
using System.Collections.Generic;

using Ecng.Common;
using Ecng.Collections;
using Ecng.Serialization;

using StockSharp.Algo.Indicators;
using StockSharp.Algo.Strategies;
using StockSharp.BusinessEntities;
using StockSharp.Messages;

namespace StockSharp.Samples.Strategies;

/// <summary>
/// Minimal port of the Frank Ud averaging expert from MetaTrader.
/// The strategy opens hedged martingale grids and liquidates both sides
/// once the newest position reaches the configured profit in pips.
/// </summary>
public class FrankUdMinimalStrategy : Strategy
{
	// Forex convention this expert came from: one pip is roughly a ten-thousandth of the quoted
	// price (0.0001 on EURUSD at 1.10, 0.01 on USDJPY at 150). Expressing it as a fraction of the
	// price keeps the same grid spacing on instruments quoted in five figures.
	private const decimal _pipFraction = 0.0001m;

	private readonly StrategyParam<decimal> _takeProfitPips;
	private readonly StrategyParam<decimal> _reEntryPips;
	private readonly StrategyParam<decimal> _initialVolume;
	private readonly StrategyParam<decimal> _minimumFreeMarginRatio;
	private readonly StrategyParam<decimal> _extraTakeProfitPips;
	private readonly StrategyParam<DataType> _candleType;

	private readonly List<PositionEntry> _longEntries = new();
	private readonly List<PositionEntry> _shortEntries = new();

	private decimal _pointValue;
	private decimal _takeProfitThreshold;
	private decimal _takeProfitDistance;
	private decimal _reEntryDistance;
	private decimal _baseVolume;
	private decimal _lastBid;
	private decimal _lastAsk;

	/// <summary>
	/// Creates a new instance of <see cref="FrankUdMinimalStrategy"/> with default parameters.
	/// </summary>
	public FrankUdMinimalStrategy()
	{
		_takeProfitPips = Param(nameof(TakeProfitPips), 65m)
		.SetDisplay("Profit trigger (pips)", "Pip profit that forces an exit of all positions.", "Risk")
		.SetGreaterThanZero();

		_reEntryPips = Param(nameof(ReEntryPips), 41m)
		.SetDisplay("Re-entry distance (pips)", "Pip distance required before adding the next grid order.", "Grid")
		.SetGreaterThanZero();

		_initialVolume = Param(nameof(InitialVolume), 0.1m)
		.SetDisplay("Initial volume", "Base lot used for the very first order.", "Risk")
		.SetGreaterThanZero();

		_minimumFreeMarginRatio = Param(nameof(MinimumFreeMarginRatio), 0.5m)
		.SetDisplay("Free margin ratio", "Free margin must stay above Balance × Ratio before adding orders.", "Risk")
		.SetNotNegative();

		_extraTakeProfitPips = Param(nameof(ExtraTakeProfitPips), 25m)
		.SetDisplay("Buffer profit (pips)", "Additional pip distance applied when calculating buffered targets.", "Risk")
		.SetNotNegative();

		_candleType = Param(nameof(CandleType), TimeSpan.FromMinutes(1).TimeFrame())
		.SetDisplay("Candle type", "Candle series the grid reacts to.", "General");
}

	/// <summary>
	/// Profit threshold expressed in pips.
	/// </summary>
	public decimal TakeProfitPips
	{
		get => _takeProfitPips.Value;
		set => _takeProfitPips.Value = value;
	}

	/// <summary>
	/// Distance in pips between consecutive martingale entries.
	/// </summary>
	public decimal ReEntryPips
	{
		get => _reEntryPips.Value;
		set => _reEntryPips.Value = value;
	}

	/// <summary>
	/// Base lot volume for the very first order.
	/// </summary>
	public decimal InitialVolume
	{
		get => _initialVolume.Value;
		set => _initialVolume.Value = value;
	}

	/// <summary>
	/// Minimal free margin ratio required to send new orders.
	/// </summary>
	public decimal MinimumFreeMarginRatio
{
		get => _minimumFreeMarginRatio.Value;
		set => _minimumFreeMarginRatio.Value = value;
}

	/// <summary>
	/// Additional pip buffer added to the take-profit distance.
	/// </summary>
	public decimal ExtraTakeProfitPips
	{
		get => _extraTakeProfitPips.Value;
		set => _extraTakeProfitPips.Value = value;
	}

	/// <summary>
	/// Candle series the grid reacts to.
	/// </summary>
	public DataType CandleType
	{
		get => _candleType.Value;
		set => _candleType.Value = value;
	}

	/// <inheritdoc />
	protected override void OnReseted()
	{
		base.OnReseted();

		_longEntries.Clear();
		_shortEntries.Clear();

		_pointValue = 0m;
		_takeProfitThreshold = 0m;
		_takeProfitDistance = 0m;
		_reEntryDistance = 0m;
		_baseVolume = 0m;
		_lastBid = 0m;
		_lastAsk = 0m;
	}

	/// <inheritdoc />
	protected override void OnStarted2(DateTime time)
	{
		base.OnStarted2(time);

		// The pip and the distances derived from it need a quote, so they are set up on the first one.
		_takeProfitThreshold = TakeProfitPips;
		_baseVolume = AdjustVolume(InitialVolume);

		SubscribeCandles(CandleType)
		.Bind(ProcessCandle)
		.Start();
	}

	private void ProcessCandle(ICandleMessage candle)
	{
		if (candle.State != CandleStates.Finished)
		return;

		// The bundled history carries no book, so the close stands for both sides of the quote.
		_lastBid = candle.ClosePrice;
		_lastAsk = candle.ClosePrice;

		if (_lastBid <= 0m || _lastAsk <= 0m)
		return;

		if (!TryInitializePip())
		return;

		if (ShouldCloseLong())
		CloseLongPositions();

		if (ShouldCloseShort())
		CloseShortPositions();

		if (ShouldOpenLong())
		OpenLongPosition();

		if (ShouldOpenShort())
		OpenShortPosition();
	}

	private bool TryInitializePip()
	{
		if (_pointValue > 0m)
		return true;

		var reference = (_lastBid + _lastAsk) / 2m;
		if (reference <= 0m)
		return false;

		// A missing or zero price step simply leaves the pip unfloored; the fraction alone already
		// keeps it positive.
		var floor = Security?.PriceStep is decimal step && step > 0m ? step : 0m;

		// Frozen for the rest of the run: a pip that followed the price would move the grid under itself.
		_pointValue = Math.Max(reference * _pipFraction, floor);
		_takeProfitDistance = (TakeProfitPips + ExtraTakeProfitPips) * _pointValue;
		_reEntryDistance = ReEntryPips * _pointValue;

		return true;
	}

	private bool ShouldCloseLong()
	{
		if (_longEntries.Count == 0)
		return false;

		var entry = GetMaxVolumeEntry(_longEntries);
		if (entry == null)
		return false;

		var profitPips = (_lastBid - entry.Price) / _pointValue;
		var bufferedTarget = entry.Price + _takeProfitDistance;
		var reachedBufferedTarget = _takeProfitDistance > 0m && _lastBid >= bufferedTarget;

		return profitPips > _takeProfitThreshold || reachedBufferedTarget;
	}

	private bool ShouldCloseShort()
	{
		if (_shortEntries.Count == 0)
		return false;

		var entry = GetMaxVolumeEntry(_shortEntries);
		if (entry == null)
		return false;

		var profitPips = (entry.Price - _lastAsk) / _pointValue;
		var bufferedTarget = entry.Price - _takeProfitDistance;
		var reachedBufferedTarget = _takeProfitDistance > 0m && _lastAsk <= bufferedTarget;

		return profitPips > _takeProfitThreshold || reachedBufferedTarget;
	}

	private bool ShouldOpenLong()
	{
		if (_baseVolume <= 0m)
		return false;

		if (!HasEnoughMargin())
		return false;

		if (_longEntries.Count == 0)
		return true;

		var lowestPrice = GetExtremePrice(_longEntries, true);
		return lowestPrice - _reEntryDistance > _lastAsk;
	}

	private bool ShouldOpenShort()
	{
		if (_baseVolume <= 0m)
		return false;

		if (!HasEnoughMargin())
		return false;

		if (_shortEntries.Count == 0)
		return true;

		var highestPrice = GetExtremePrice(_shortEntries, false);
		return highestPrice + _reEntryDistance < _lastBid;
	}

	private void OpenLongPosition()
	{
		var volume = DetermineNextVolume(_longEntries);
		if (volume <= 0m)
		return;

		BuyMarket(volume);
		AddEntry(_longEntries, _lastAsk, volume);
	}

	private void OpenShortPosition()
	{
		var volume = DetermineNextVolume(_shortEntries);
		if (volume <= 0m)
		return;

		SellMarket(volume);
		AddEntry(_shortEntries, _lastBid, volume);
	}

	private void CloseLongPositions()
	{
		var volume = GetTotalVolume(_longEntries);
		if (volume <= 0m)
		return;

		SellMarket(volume);
		_longEntries.Clear();
	}

	private void CloseShortPositions()
	{
		var volume = GetTotalVolume(_shortEntries);
		if (volume <= 0m)
		return;

		BuyMarket(volume);
		_shortEntries.Clear();
	}

	private decimal DetermineNextVolume(List<PositionEntry> entries)
	{
		if (_baseVolume <= 0m)
		return 0m;

		var volume = entries.Count == 0
		? _baseVolume
		: GetMaxVolume(entries) * 2m;

		return AdjustVolume(volume);
	}

	private decimal AdjustVolume(decimal volume)
	{
		if (volume <= 0m)
		return 0m;

		var security = Security;

		if (security?.VolumeStep is decimal step && step > 0m)
		{
			var steps = Math.Floor(volume / step);
			volume = steps * step;
		}

		if (security?.MinVolume is decimal min && min > 0m && volume < min)
		volume = min;

		if (security?.MaxVolume is decimal max && max > 0m && volume > max)
		volume = max;

		return volume;
	}

	private bool HasEnoughMargin()
	{
		if (MinimumFreeMarginRatio <= 0m)
		return true;

		var portfolio = Portfolio;
		if (portfolio == null)
		return true;

		var balance = portfolio.CurrentValue ?? portfolio.BeginValue ?? 0m;
		if (balance <= 0m)
		return true;

		var blocked = portfolio.Commission ?? 0m;
		var baseValue = portfolio.CurrentValue ?? portfolio.BeginValue;
		if (baseValue == null)
		return true;

		var freeMargin = baseValue.Value - blocked;
		return freeMargin > balance * MinimumFreeMarginRatio;
	}

	private static void AddEntry(List<PositionEntry> entries, decimal price, decimal volume)
	{
		if (volume <= 0m)
		return;

		entries.Add(new PositionEntry(price, volume));
	}

	private static decimal GetTotalVolume(List<PositionEntry> entries)
	{
		decimal total = 0m;

		foreach (var entry in entries)
		total += entry.Volume;

		return total;
	}

	private static PositionEntry GetMaxVolumeEntry(List<PositionEntry> entries)
	{
		PositionEntry result = null;
		decimal maxVolume = 0m;

		foreach (var entry in entries)
		{
			if (entry.Volume > maxVolume)
			{
				maxVolume = entry.Volume;
				result = entry;
			}
		}

		return result;
	}

	private static decimal GetMaxVolume(List<PositionEntry> entries)
	{
		decimal maxVolume = 0m;

		foreach (var entry in entries)
		if (entry.Volume > maxVolume)
		maxVolume = entry.Volume;

		return maxVolume;
	}

	private static decimal GetExtremePrice(List<PositionEntry> entries, bool isLong)
	{
		var hasValue = false;
		decimal result = 0m;

		foreach (var entry in entries)
		{
			var price = entry.Price;

			if (!hasValue)
			{
				result = price;
				hasValue = true;
				continue;
			}

			if (isLong)
			{
				if (price < result)
				result = price;
			}
			else if (price > result)
			{
				result = price;
			}
		}

		return result;
	}

	private sealed class PositionEntry
	{
		public PositionEntry(decimal price, decimal volume)
		{
			Price = price;
			Volume = volume;
		}

		public decimal Price { get; }

		public decimal Volume { get; }
	}
}