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
MetaTrader5configurada 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.timeretornado 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
Metadata
Release files for mtcli-tradehistory 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mtcli_tradehistory-1.0.0.tar.gz | 17.4 kB | Without provenance | Details for mtcli_tradehistory-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mtcli_tradehistory-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for mtcli_tradehistory-1.0.0-py3-none-any.whl |
Total release size: 36.7 kB
Release files / mtcli_tradehistory-1.0.0.tar.gz
| Download URL | mtcli_tradehistory-1.0.0.tar.gz |
|---|---|
| Size | 17.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e82afd36f4268ec1b805d0dade2dde943ad97dd2653ca7f2884e40f447c049d2
|
|
BLAKE2b-256 checksum How to use checksums |
35d1c6d42de1b7c78f832fc9b667ad1af6c74d2ed6adea13b6adf5c977f5b372
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.13.7 Windows/11
|
Release files / mtcli_tradehistory-1.0.0-py3-none-any.whl
| Download URL | mtcli_tradehistory-1.0.0-py3-none-any.whl |
|---|---|
| Size | 19.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
378db8578b8b3ba40ed50246607c118f52cf70fc562b8878e5307a8312af4d8f
|
|
BLAKE2b-256 checksum How to use checksums |
45e1fbfc7375df5f3b7caa32850bf8c69857a0af53041535cd38f2ce551543e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.13.7 Windows/11
|
Security for mtcli-tradehistory 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.