Idioma: Português · English
O Didi mantém, na sua máquina, uma base de cotações históricas da B3, proventos e eventos corporativos da CVM e taxas do Banco Central, e a expõe por linha de comando, por um servidor MCP para assistentes de IA, por uma API HTTP local e por um pacote Go.
A ideia é simples: quando você pergunta a um assistente "quanto rendeu PETR4 desde 2023 contra o CDI?", ele deve responder a partir de dados que você controla e pode conferir, com data e origem, e não de memória.
didi import ~/Downloads/COTAHIST_A2025.ZIP # arquivo baixado da B3
didi update --download --events --rates # mantém cotações, eventos e taxas em dia
didi compare PETR4 --benchmark CDI --from 2023-01-01
didi mcp # servidor MCP para o seu assistente- Cotações diárias de todo o mercado à vista da B3 (ações, units, FIIs, ETFs, BDRs, fracionário), importadas dos arquivos COTAHIST, com carga atômica, idempotente e com a origem de cada linha.
- Eventos corporativos: dividendos e JCP lidos dos documentos da CVM, desdobramentos e grupamentos propostos por um detector e confirmados por você, e a série ajustada recalculada a partir deles.
- Indicadores: retorno, CAGR, volatilidade, drawdown e médias móveis; comparação com CDI, SELIC e ETFs; retorno real deflacionado pelo IPCA.
- Sinais e triagem: condições factuais datadas de um papel (distância da máxima de 52 semanas, yield dos últimos 12 meses...) e a lista dos papéis que satisfazem critérios seus.
- Carteira (opcional): você registra compras e vendas; posição, preço médio, proventos e rentabilidade são derivados a cada consulta.
- Quatro portas, um núcleo: CLI, servidor MCP, API HTTP local e pacote Go, com os mesmos contratos.
- Não recomenda. O Didi devolve fatos e estatísticas derivadas, com data, janela e fonte. Não diz o que comprar ou vender, não dá nota e não ranqueia por mérito; as tools dizem isso ao assistente. A razão está na ADR-0001.
- Não apura imposto. A carteira expõe os insumos (vendas por mês e classe, preço médio, resultado), não o valor devido (ADR-0002).
- Não traz dados. O repositório e o binário não contêm cotações nem documentos. Você importa ou baixa os dados das fontes públicas para a sua máquina e responde pelo uso deles. Veja Fontes de dados, limites e aviso legal.
- Não tem tempo real nem intradiário, e não executa ordens.
É preciso ter Go na versão indicada em
go.mod. Não há CGO nem outra dependência: o banco é um arquivo
SQLite único.
go install github.com/phbpx/didi/cmd/didi@latestOu, a partir do código:
git clone https://github.com/phbpx/didi.git
cd didi
go build -o didi ./cmd/didiOs dados ficam em ~/.didi (ou em $DIDI_HOME, ou onde --data apontar).
# 1. Baixe um arquivo de cotações históricas (COTAHIST) no site da B3 e importe
didi import ~/Downloads/COTAHIST_A2025.ZIP
# 2. Veja o que a base tem
didi status
didi search petr
didi query PETR4 --from 2025-01-01 --to 2025-03-31
# 3. Carregue eventos corporativos e taxas de referência
didi events update
didi rates update
# 4. Faça perguntas
didi adjusted PETR4 --from 2025-01-01
didi indicators PETR4 --from 2023-01-01
didi signals PETR4O guia Primeiros passos percorre isso com calma, incluindo a atualização diária.
O servidor MCP é somente leitura e fala por entrada e saída padrão.
claude mcp add didi -- /caminho/para/didi mcpPara o Claude Desktop e outros clientes, e para a lista das tools, veja
Servidor MCP para assistentes. As tools da carteira ficam
ligadas por padrão; didi mcp --no-portfolio as esconde.
| Guia | Para quê |
|---|---|
| Primeiros passos | Do zero a uma base funcionando |
| Conceitos e semântica | Como ler os resultados sem se enganar |
| Eventos corporativos e série ajustada | Proventos, desdobramentos, duplicatas e revisão |
| Indicadores, benchmarks e retorno real | Retorno, risco, CDI, IPCA |
| Sinais e triagem | Condições factuais e busca por critérios |
| Carteira | Movimentações, posição, proventos, rentabilidade |
| Servidor MCP | Ligação com assistentes e referência das tools |
| Referência da CLI | Todos os comandos e opções |
| API HTTP | Rotas, parâmetros e erros |
| Pacote Go | Uso do núcleo no seu programa |
| Fontes de dados e aviso legal | De onde vem cada dado e o que falta |
| Backup e restauração | Cópia consistente da base |
| Solução de problemas | Situações comuns e perguntas frequentes |
| Arquitetura | Como o código se organiza |
O raciocínio por trás de cada decisão está em docs/design/:
requisitos, decisões de arquitetura, estudos de fonte e o roteiro.
O Didi declara as próprias lacunas, e a cobertura (didi coverage,
didi events coverage) as repete. As principais:
- Proventos em dinheiro só existem em forma estruturada na CVM desde outubro de 2022; antes disso, apenas com entrada manual.
- Rendimentos de FIIs e proventos de BDRs e ETFs não têm fonte automática:
entram por
didi events import-csv. - Desdobramentos, grupamentos e bonificações não têm fonte estruturada: vêm do detector de saltos de preço e da sua confirmação.
- Não há dados fundamentalistas (lucro, payout, dívida) nem classificação setorial.
- A importação dos extratos da Área do Investidor da B3 ainda não foi validada contra arquivos reais.
Contribuições são bem-vindas. Leia o CONTRIBUTING.md, que explica o que cabe no projeto e o que um pull request precisa ter, e o código de conduta. Falhas de segurança seguem o SECURITY.md. As mudanças de cada versão estão no CHANGELOG.md.
Distribuído sob a licença MIT.
O Didi é uma ferramenta de uso pessoal para consulta de dados públicos. Não é recomendação de investimento, não substitui um profissional habilitado e não tem vínculo com a B3, a CVM ou o Banco Central. Os dados podem estar incompletos ou errados, e o software é fornecido sem garantia.
