Executar comandos do cTrader CLI¶

Este artigo explica como são estruturados os comandos do cTrader CLI, como funciona a autenticação e como consultar dados de contas, preços e histórico.

Estrutura dos comandos ¶

Todos os comandos do cTrader CLI seguem a mesma estrutura:

ctrader-cli <command> [arguments] [options]

• As opções começam com um prefixo. -- indica a forma longa e - a forma curta (--symbol e -s são equivalentes).
• Os valores das opções são separados por um espaço ou pelo sinal de igual. Tanto --symbol EURUSD como --symbol=EURUSD são válidos.
• Os argumentos são valores posicionais sem prefixo. O caminho para um ficheiro .algo é um argumento.
• Os valores que contêm espaços devem ser colocados entre aspas simples ou duplas, por exemplo '/opt/my cbots/trend cbot.algo'. Utilize sempre o mesmo tipo de aspas dentro de cada comando.

Autenticação ¶

O cTrader CLI utiliza dois modos de autenticação. Ambos utilizam o ficheiro de credenciais que prepara durante a configuração.

Os comandos accounts, symbols, metadata, run e backtest, disponíveis em ambos os modos, são executados em lote ou de forma interativa conforme as opções indicadas:

• Modo em lote – lê as credenciais de --pwd-file (ou --broker) e é executado sem interação.
• Modo interativo – utiliza --password e -q (ou qualquer opção específica do comando) e executa uma chamada interativa.

Identificadores de períodos ¶

Muitos comandos aceitam um valor --period. Execute ctrader-cli periods para listar todos os identificadores aceites. Os identificadores abrangem minutos, horas, dias, semanas e meses, bem como ticks, Renko, barras Range e variantes Heikin Ashi. A interpretação dos identificadores não distingue maiúsculas de minúsculas.

Unidades de volume ¶

--volume aceita unidades da moeda base ou lotes. Utilize --volume-type=units (predefinido) ou --volume-type=lots para definir como interpretar o volume. Para a maioria dos símbolos Forex, 100 000 unidades correspondem a um lote padrão.

ctrader-cli symbol --ctid=letstrade --pwd-file=C:/test/password.pwd --account=1234567 -q --symbol=XAUUSD

Datas e horas ¶

Todas as datas e horas no cTrader CLI são expressas em UTC. A CLI nunca utiliza o fuso horário local do seu computador nem a hora do servidor da corretora.

O UTC aplica-se à saída dos comandos e às datas introduzidas da seguinte forma:

• Saída: todas as marcas temporais na saída JSON são apresentadas em UTC, no formato ISO 8601 com Z, por exemplo 2026-10-08T14:05:00.000Z.
• Comandos interativos (candles, deals, orders-history e backtest executado com -q): --from e --to aceitam apenas uma data, no formato yyyy-MM-dd, dd/MM/yyyy, dd-MM-yyyy ou yyyy/MM/dd. A data corresponde a um dia de calendário em UTC.
  • Para deals e orders-history, --to inclui o dia inteiro, até às 23:59:59 UTC.
  • Para candles, --to corresponde ao início desse dia (00:00 UTC). Para incluir um dia inteiro, defina --to como o dia seguinte.
  • Sem --from / --to, o backtest interativo abrange os últimos 7 dias.
• Comandos em lote (backtest e outros): as datas usam dd/MM/yyyy, opcionalmente com uma hora no formato de 24 horas dd/MM/yyyy HH:mm, por exemplo 31/12/2026 18:00, também em UTC.

A única exceção é um cBot em execução (run, backtest). A hora segue a definição TimeZone configurada no cBot, tal como no cTrader Algo.

Consultar dados de contas e do mercado ¶

ctrader-cli periods não requer nenhuma conta nem credenciais, pelo que é um bom primeiro teste.

ctrader-cli periods

Liste as contas de negociação associadas ao seu cTrader ID:

ctrader-cli accounts --ctid=letstrade --pwd-file=C:/test/password.pwd

Depois de obter o número da conta, liste os símbolos disponíveis nessa conta:

ctrader-cli symbols --ctid=letstrade --pwd-file=C:/test/password.pwd --account=1234567

Consulte o preço atual de um símbolo e obtenha velas históricas através de um script:

ctrader-cli price --ctid=letstrade --password=secret --account=1234567 -q --symbol=EURUSD
ctrader-cli candles --ctid=letstrade --password=secret --account=1234567 -q --symbol=EURUSD --period=h1 --count=200 > eurUSD_h1.json

Limites do histórico ¶

Os comandos deals e orders-history estão sujeitos aos seguintes limites de histórico:

• A CLI carrega todo o intervalo definido por --from / --to, sem limite de duração.
• Uma chamada devolve apenas as 200 transações mais recentes (deals) ou as 500 ordens mais recentes (orders-history) desse intervalo.
• Sem --from / --to, ambos os comandos devolvem apenas os dados dos últimos 30 dias.

• --count define o número de registos a devolver:

  • 50 por predefinição e até 200 para deals.
  • 100 por predefinição e até 500 para orders-history.

Se indicar --from ou --to, --count é ignorado e a chamada devolve até ao número máximo de registos.

Se um intervalo contiver mais registos do que uma chamada consegue devolver, divida-o em intervalos mais curtos e execute o comando para cada um.

Para verificar se os resultados foram truncados, consulte a saída:

• orders-history: a saída contém os campos available e returned. Se available for superior a returned, existem mais ordens no intervalo.
• deals: se count for exatamente 200, pode haver mais negociações no intervalo.

Ações em massa na shell interativa ¶

Na shell interativa, vários comandos permitem acrescentar all e yes no fim para executar ações em massa sem pedir confirmação.

Executar comandos de forma interativa ¶

Execute ctrader-cli sem indicar um comando para abrir a shell interativa. Quando solicitado, inicie sessão com o seu cTID e a palavra-passe. Depois, introduza vários comandos consecutivos sem ter de voltar a fornecer as credenciais. Este modo é útil quando pretende executar vários comandos seguidos.

Para executar um único comando e sair imediatamente a seguir, acrescente -q. Esta opção é útil em scripts, nos quais o processo deve terminar assim que o comando estiver concluído.

Duas opções ajudam a descobrir as funcionalidades suportadas pela CLI.

Se o seu cTrader ID estiver associado a contas de várias corretoras com o mesmo número de conta, acrescente --broker=<broker-name> para eliminar a ambiguidade.

Erros comuns ¶