Guia Técnico: Como Utilizar CopyRates() na Prática

Se você já tentou extrair preços históricos direto do MetaTrader 5, provavelmente se deparou com mensagens de erro, buffers vazios ou com dados fora de sincronia. A raiz do problema costuma estar na forma como a função CopyRates() é chamada: parâmetros mal alinhados, intervalos de tempo incompatíveis e a falta de tratamento de retornos podem transformar um simples pull de candles em um pesadelo de performance.

Entendendo a estrutura MqlRates

• time – timestamp do início do candle (UTC).
• open, high, low, close – preços brutos, já convertidos para o tipo double.
• tick_volume – número de ticks que compuseram o candle.
• spread e real_volume – raramente usados, mas críticos em estratégias de scalping.

Passo a passo prático

1. Defina o símbolo e o período de tempo. Evite _Symbol genérico se o EA for multi‑ativo; prefira uma variável passada como argumento.

2. Calcule o from e o to em timestamps. Um erro comum é usar TimeCurrent() para to e TimeCurrent() - 86400 * n para from sem considerar o fuso do servidor.

3. Alocação de buffer: MqlRates rates[]; – o array deve ser dimensionado dinamicamente com ArrayResize após a chamada.

4. Chamada segura:

int copied = CopyRates(symbol, timeframe, from, to, rates); if(copied <= 0){ Print("Falha ao copiar: ", GetLastError()); return(false); } ArraySetAsSeries(rates, true); 

5. Validação de lacunas. Mesmo com copied > 0, gaps podem aparecer quando o mercado está fechado. Use um laço para pular entradas com rates[i].time == 0.

Performance e armadilhas

O maior gargalo costuma ser a quantidade de candles solicitada. Pedir 10 000 barras de 1 minuto gera mais tráfego de rede que um pedido de 500 barras de 1 hora. A solução prática: paginar as requisições. Por exemplo, baixe 1 000 candles por vez e concatene.

Outro ponto crítico – garbage collection. Cada chamada cria um novo array; se o EA roda em loop, o consumo de memória pode subir exponencialmente. Reutilize o mesmo buffer e limpe com ArrayFree(rates) antes de sair.

Casos de uso típicos

• Back‑testing de estratégias de breakout: copie candles diários dos últimos 2 anos, calcule a volatilidade média e filtre por spreads < 1 ponto.
• Indicadores de volume: use tick_volume para normalizar o peso de cada barra em um oscilador customizado.
• Sincronização de múltiplos timeframes: copie o mesmo intervalo em M5, H1 e D1; alinhe-os usando o timestamp como chave.

Quando CopyRates() falha

Se o servidor está em modo “maintenance”, a chamada retorna -1 e GetLastError() entrega 4105. A solução não é retry infinito; implemente back‑off exponencial e registre a falha para auditoria.

Em mercados de alta volatilidade (ex.: anúncios de juros), o feed pode pular candles. Nesses momentos, valide a sequência de timestamps: if(rates[i].time - rates[i+1].time != PeriodSeconds(timeframe)) e descarte a barra incompleta.

Para quem ainda não testou, experimente o snippet acima em um script simples e ajuste os parâmetros de from/to até obter um array estável. Caso precise de um exemplo completo, confira o tutorial oficial que demonstra a integração com um algoritmo de média móvel.

1. Primeiros passos após instalar a biblioteca

Abra o MetaEditor, crie um novo script e inclua #include . Em seguida, declare a variável:

COPY_RATES cr;

Instancie o objeto no OnInit():

int OnInit() { cr.SetSymbol(_Symbol); cr.SetPeriod(PERIOD_CURRENT); return(INIT_SUCCEEDED); }

2. Configuração inicial – parâmetros essenciais

• Symbol: par de moedas ou ativo que será analisado.
• Period: timeframe (M1, H1, D1 etc.).
• Shift: deslocamento para iniciar a leitura (0 = vela atual).
• Count: número de candles a copiar.

Exemplo de chamada:

MqlRates rates[]; int copied = cr.Copy(_Symbol, PERIOD_H1, 0, 500, rates);

Se copied for menor que Count, verifique as limitações de histórico.

3. Rotina recomendada – leitura e análise dos candles

Estruture a lógica dentro de OnTick() ou em um timer de 1 minuto. O fluxo básico:

1. Chamar Copy() com Count = 100 (últimas 100 velas).
2. Iterar sobre o array rates[] de trás para frente.
3. Extrair open, high, low, close, volume e calcular indicadores (ex.: SMA, RSI).
4. Armazenar resultados em buffers para uso posterior ou para gerar sinais.

4. Checklist operacional – evitar erros comuns

5. Aceleração de resultados – otimizações de performance

Use ArraySetAsSeries(rates, true) para que o índice 0 seja a vela mais recente; isso reduz a necessidade de inversão de loops.

Limite a frequência de chamadas: um Copy() a cada 5 ticks já é suficiente para a maioria dos indicadores, evitando sobrecarga de CPU.

Quando precisar de múltiplos períodos simultâneos, prefira CopyRatesArray() em vez de chamadas individuais, pois ele realiza um único acesso ao histórico.

6. Mini‑dashboard de progresso semanal

Dia | Candles lidos | Sinais gerados | Erros ----|----------------|----------------|------ Seg | 4.800 | 12 | 0 Ter | 4.800 | 15 | 1 Qua | 4.800 | 13 | 0 Qui | 4.800 | 14 | 0 Sex | 4.800 | 16 | 0 

Atualize a planilha ao final de cada dia. Um aumento consistente nos “Sinais gerados” indica que a parametrização está alinhada ao mercado; quedas repentinas sinalizam necessidade de rever Shift ou Count.

7. Hábitos complementares para evitar abandono

• Documente cada ajuste em um CHANGELOG.txt.
• Teste a estratégia em modo Strategy Tester antes de rodar ao vivo.
• Configure alertas de erro (ex.: Print() ou Alert()) para detectar falhas de Copy() imediatamente.

⚠️ Dica de ouro: se a chamada Copy() retornar -1, o histórico está corrompido. Re‑baixe os dados via Tools → History Center antes de prosseguir.

Perfil Ideal e Limitações Práticas do CopyRates()

Se você vive no universo MetaTrader e depende de dados de preços históricos para calibrar robôs, CopyRates() pode ser seu trunfo; caso contrário, provavelmente será apenas mais um bloco de código que ocupa espaço.

Quem deve usar?

• Quant traders que rodam backtests em massa e precisam de acesso direto ao MqlRates sem abrir arquivos CSV.
• Desenvolvedores de EAs que manipulam múltiplos símbolos simultaneamente e exigem consistência de timezone.
• Analistas de mercado que cruzam candles de diferentes períodos em tempo real para detectar divergências.

Quem não vai aproveitar?

• Iniciantes ainda aprendendo a sintaxe MQL4/MQL5 – a curva de aprendizagem já é íngreme.
• Usuários que dependem de feeds externos (ex.: Bloomberg) – o método só traz dados internos ao broker.
• Quem roda apenas estratégias “buy‑and‑hold” – o ganho de performance aqui é marginal.

Limitações contextuais

O retorno de CopyRates() está preso ao histórico disponibilizado pelo servidor. Se o broker mantiver apenas 3 meses de dados, seu backtest ficará artificialmente restrito. A função também não oferece compressão; em loops intensivos de 10 000 chamadas, o consumo de CPU pode subir 30 % frente ao uso de CopyTime() + CopyOpen() combinados.

FAQ rápido

Checklist de implantação

• Verificar HistoryDepth() do broker.
• Testar chamada única antes de inserir em loops.
• Implementar fallback para CopyTicks() caso CopyRates() retorne INVALID_PARAMETER.
• Medir tempo de execução com GetTickCount() nas primeiras 100 iterações.

Parecer editorial

Em termos de prática real, CopyRates() entrega rapidez quando a estrutura de dados é essencial – um ganho de até 15 ms por 500 candles comparado a chamadas múltiplas. Contudo, esse benefício desaparece em ambientes com latência de rede alta ou servidores que limitam o histórico. Portanto, o produto veste bem quem tem controle total sobre o broker e necessita de alta frequência de leitura; fora desse nicho, o custo de complexidade supera a vantagem.

Decisão: adote CopyRates() se seu workflow já inclui manipulação intensiva de MqlRates e você tem acesso a histórico profundo. Caso contrário, persista com as chamadas segmentadas que oferecem mais robustez frente a “gaps” e limites de servidor.

Acesse a página oficial