Skip to content
phbpxPublic

About

Base local de cotações históricas da B3, eventos da CVM e taxas do Banco Central, com CLI, servidor MCP para assistentes, API HTTP e pacote Go. / Local base of B3 historical quotes with a CLI, an MCP server, an HTTP API and a Go package.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Didi

Idioma: Português · English

CI Go Reference Licença: MIT

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

O que ele faz

  • 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.

O que ele não faz

  • 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.

Instalação

É 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@latest

Ou, a partir do código:

git clone https://github.com/phbpx/didi.git
cd didi
go build -o didi ./cmd/didi

Os dados ficam em ~/.didi (ou em $DIDI_HOME, ou onde --data apontar).

Primeiros passos

# 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 PETR4

O guia Primeiros passos percorre isso com calma, incluindo a atualização diária.

Com um assistente (MCP)

O servidor MCP é somente leitura e fala por entrada e saída padrão.

claude mcp add didi -- /caminho/para/didi mcp

Para 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.

Documentação

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.

Limites conhecidos

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.

Contribuindo

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.

Licença e aviso

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.

About

Base local de cotações históricas da B3, eventos da CVM e taxas do Banco Central, com CLI, servidor MCP para assistentes, API HTTP e pacote Go. / Local base of B3 historical quotes with a CLI, an MCP server, an HTTP API and a Go package.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages