mtcli-tradehistory

Plugin mtcli para exibir o histórico de negócios (trades/deals) executados pelo usuário em um pregão, utilizando a API oficial do MetaTrader 5.

O foco do plugin é pós-trade, auditoria e leitura cronológica, com saída 100% textual, adequada para terminal e leitores de tela (NVDA / JAWS).

---

Funcionalidades

• Exibe todos os deals executados no pregão
• Filtro por:
  • Data do pregão
  • Ativo (símbolo)
• Informações exibidas:
  • Horário do negócio
  • Tipo (BUY / SELL)
  • Preço
  • Volume
  • Resultado financeiro (P&L)
  • Identificador da posição
• Arquitetura MVC
• Saída textual simples e acessível
• Controle explícito de fuso horário do servidor MT5

---

Estrutura do projeto

mtcli-tradehistory/
├── README.md
├── pyproject.toml
└── mtcli_tradehistory/
├── **init**.py
├── cli.py          # Interface CLI (Click)
├── conf.py         # Configurações do plugin
├── controller.py  # Regras de orquestração
├── model.py       # Acesso à API MetaTrader5
└── view.py        # Saída textual no terminal

---

Instalação

Clone o repositório e instale em modo editável:

git clone https://github.com/seu-usuario/mtcli-tradehistory.git
cd mtcli-tradehistory
pip install -e .

Requisitos:

• Python 3.10+
• MetaTrader 5 instalado
• Biblioteca MetaTrader5 configurada corretamente

---

Uso

Pregão do dia atual

mt th

Pregão específico

mt th --date 2026-01-09

Pregão + ativo

mt th --date 2026-01-09 --symbol WING26

---

Configuração

As configurações podem ser feitas via:

• variáveis de ambiente
• arquivo padrão do mtcli

SERVER_TZ_OFFSET (OBRIGATÓRIO)

Define o fuso horário do servidor da corretora.

⚠️ A API do MetaTrader 5 não informa o fuso do servidor. Por isso, este valor deve ser configurado explicitamente.

Exemplos:

Servidor	Valor
UTC	0
UTC+3	3
UTC-3	-3

Exemplo via variável de ambiente:

set SERVER_TZ_OFFSET=0

Ou no arquivo de configuração:

[DEFAULT]
server_tz_offset = 0

---

Sobre horários (importante)

• deal.time retornado pelo MT5 está no horário do servidor
• Não é UTC
• Não é horário local do sistema
• A API não fornece o fuso automaticamente

Este plugin:

• Assume o fuso do servidor via SERVER_TZ_OFFSET
• Não aplica conversões implícitas do sistema operacional
• Exibe horários previsíveis e auditáveis

---

Acessibilidade

• Saída 100% textual
• Sem cores, gráficos ou formatações visuais complexas
• Compatível com leitores de tela (NVDA, JAWS)
• Ideal para uso em terminal (CMD, PowerShell, WSL)

---

O que este plugin NÃO faz

• Não exibe gráficos
• Não interpreta estratégia
• Não calcula estatísticas avançadas (winrate, expectancy)
• Não substitui relatórios do MT5

Ele mostra os fatos: negócios executados, em ordem cronológica.

---

Evoluções possíveis

• Agrupamento por posição (entrada → saída → resultado)
• Resumo do pregão (P&L total, nº trades, winrate)
• Exportação CSV
• Opções --server-time / --local-time
• Integração com outros plugins mtcli (VWAP, Market Profile)

---

Licença

GPL License

---

Autor

Valmir França Trader | Desenvolvedor Python | mtcli