Skip to content

robertoecf/findata-br

BranchesTags

Repository files navigation

 ███████╗██╗███╗   ██╗██████╗  █████╗ ████████╗ █████╗        ██████╗ ██████╗
 ██╔════╝██║████╗  ██║██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗       ██╔══██╗██╔══██╗
 █████╗  ██║██╔██╗ ██║██║  ██║███████║   ██║   ███████║ █████╗██████╔╝██████╔╝
 ██╔══╝  ██║██║╚██╗██║██║  ██║██╔══██║   ██║   ██╔══██║ ╚════╝██╔══██╗██╔══██╗
 ██║     ██║██║ ╚████║██████╔╝██║  ██║   ██║   ██║  ██║       ██████╔╝██║  ██║
 ╚═╝     ╚═╝╚═╝  ╚═══╝╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝       ╚═════╝ ╚═╝  ╚═╝

                   Dados financeiros abertos do Brasil
        BCB · CVM · B3 · IBGE · IPEA · Tesouro  →  API + MCP + CLI

API + servidor MCP + CLI open-source para dados financeiros brasileiros.

Agrega dados públicos de BCB, CVM, B3, IBGE, IPEA e Tesouro Nacional. De graça. Sem API key. Sem truques de rate-limit. Só Python.

CI Versão Python Licença MIT Status 

                            ▌
▛▌  ▛▌▌▌█▌  ▌▌▛▌▛▘█▌  ▛▌▀▌▛▌▛▌▀▌
▙▌  ▙▌▙▌▙▖  ▚▘▙▌▙▖▙▖  ▙▌█▌▌▌▌▌█▌
     ▌                ▄▌

    O que você ganha
  • API REST com Swagger interativo em /docs.
  • Servidor MCP montado automaticamente em /mcp — plugue o findata-br direto no Claude, Cursor, Codex.
  • CLI Python (findata ...) com tabelas ricas e banner animado em TTY.
  • Biblioteca async com connection pooling, retry com backoff exponencial e cache LRU de 15 min.
  • Registry CNPJ ↔ ticker ↔ nome embarcado no wheel (~50k entidades CVM + SUSEP + B3) — uma query resolve qualquer formato.
  • Zero autenticação, zero API keys. Todas as fontes são dados públicos governamentais.
▐▘    ▗        ▌     ▌   ▌
▜▘▛▌▛▌▜▘█▌▛▘  ▛▌█▌  ▛▌▀▌▛▌▛▌▛▘
▐ ▙▌▌▌▐▖▙▖▄▌  ▙▌▙▖  ▙▌█▌▙▌▙▌▄▌

    Fontes de dados
Fonte Domínio Cobertura Auth
BCB SGS Banco Central Selic, CDI, IPCA, IGP-M, câmbio, PIB, desemprego — 18k+ séries temporais —
BCB Olinda PTAX Banco Central USD/BRL, EUR/BRL e todas moedas rastreadas; ponto e período —
BCB Olinda Focus Banco Central Boletim Focus (semanal) — anual, mensal, Selic, Top-5 —
CVM Regulador Empresas registradas, demonstrações DFP/ITR, fatos relevantes/comunicados (IPE), formulário cadastral (FCA — ticker→CNPJ resolver, setor, DRI), catálogo + cota diária de fundos, composição da carteira (CDA), lâmina + rentabilidade mensal/anual, perfil de cotistas —
IBGE Agregados v3 Instituto de estatística IPCA detalhado por 10 grupos + 365 subitens, INPC, PIB trimestral —
IPEA Data (OData v4) Instituto de pesquisa ~8k séries macro curadas (histórico desde a década de 1940), busca no catálogo, metadados —
Tesouro Transparente Tesouro Nacional Tesouro Direto — preços e taxas históricos —
B3 Bolsa Cotações atuais via yfinance, COTAHIST oficial (1986+) ano/mês/dia, composição teórica de índices (IBOV, IBrX, SMLL, IDIV, IFIX + 14 sectoriais) —
ANBIMA Mercado IMA (família IRF-M, IMA-B, IMA-S, IMA-Geral) snapshot + histórico via formulário Série Histórica, ETTJ (curva zero), debêntures secundário —
Registry Cross-source CNPJ ↔ ticker ↔ nome resolver — SQLite FTS5 embarcado no wheel (~50k entidades CVM+SUSEP+B3); uma query MATCH cobre exato, fragmento e fuzzy — (offline)

Nota sobre ANBIMA. Usamos os arquivos públicos em www.anbima.com.br/informacoes/* (XLS / CSV / TXT atualizados diariamente), não a API comercial Sensedia (que exige cadastro institucional). Os números são os mesmos canônicos publicados pela ANBIMA — só servidos como arquivos. Se no futuro alguém da comunidade tiver acesso à API autenticada e quiser contribuir com dados em near-real-time, o framework findata.auth segue pronto pra ser reutilizado — veja docs/SOURCES_WITH_AUTH.md.

▘    ▗   ▜
▌▛▌▛▘▜▘▀▌▐ ▀▌▛▘▀▌▛▌
▌▌▌▄▌▐▖█▌▐▖█▌▙▖█▌▙▌

    Instalação

Um comando único — todas as 6 fontes (BCB, CVM, B3, IBGE, IPEA, Tesouro) ficam prontas pra usar:

pip install findata-br

O que vai ser instalado

findata-br é Python 3.11+ e depende de uma stack enxuta de bibliotecas estáveis e bem mantidas. Nada de infra, nada de banco de dados, nada de worker/broker — tudo acontece em processo único.

Pacote Versão Pra que serve
fastapi >=0.115 Servidor HTTP + geração automática da Swagger UI em /docs
uvicorn[standard] >=0.34 Loop async ASGI que serve o FastAPI (com uvloop, httptools, watchfiles)
httpx >=0.28 Cliente HTTP async usado em todas as fontes (BCB, CVM, IPEA, etc.)
pydantic >=2.0 Modelos tipados e validação das respostas de API
fastapi-mcp >=0.4 Monta o servidor MCP em /mcp a partir das rotas FastAPI
typer >=0.15 Framework da CLI findata ...
rich >=13.0 Tabelas coloridas e banner animado no terminal
slowapi >=0.1.9 Rate limiting por IP (protege o endpoint público)
yfinance >=0.2.50 Cotações B3 via Yahoo Finance (puxa pandas/numpy como deps transitivas)

Total instalado: ~70 MB (a maior fatia é pandas + numpy, transitivas do yfinance). Se seu deploy precisa ser mais enxuto e você não usa as rotas /b3/*, dá pra pular o yfinance — veja a seção Instalação mínima abaixo.

Instalação mínima

Só quer as fontes de dados públicos sem yfinance/pandas/numpy? Instale sem deps e adicione só o que precisar:

pip install findata-br --no-deps
pip install fastapi 'uvicorn[standard]' httpx pydantic fastapi-mcp typer rich slowapi

Isso economiza ~40 MB mas as rotas /b3/* e o comando findata b3 ... vão retornar 503 Service Unavailable até yfinance ser instalado.

Desenvolvimento local

git clone https://github.com/robertoecf/findata-br.git
cd findata-br
pip install -e '.[dev]'           # core + pytest, ruff, mypy, respx
bash scripts/git/install-hooks.sh # pre-commit + pre-push hooks
▌▌▛▘▛▌
▙▌▄▌▙▌

    Uso

CLI

findata bcb series              # catálogo de séries nomeadas
findata bcb get selic -n 10     # últimos 10 valores da Selic
findata bcb get ipca            # IPCA mensal
findata bcb ptax                # USD/BRL de hoje
findata bcb focus -i IPCA -n 5  # expectativas do Focus

findata tesouro search IPCA+
findata tesouro history "Tesouro IPCA+ 2035" -n 30

findata ibge ipca -n 6          # IPCA quebrado por grupo

findata ipea catalog            # séries IPEA curadas
findata ipea search desemprego  # busca full-text em ~8k séries
findata ipea get BM12_TJOVER12 -n 12

findata cvm search Petrobras

# Fundos: holdings (CDA), lâmina, perfil de cotistas
findata cvm holdings 00.280.302/0001-60 -y 2026 -m 3
findata cvm lamina   00.280.302/0001-60 -y 2026 -m 3
findata cvm profile  00.280.302/0001-60 -y 2026 -m 3

findata b3 quote PETR4
findata b3 history VALE3 -p 1y

findata anbima ima                          # snapshot do dia (todos os índices)
findata anbima ima -i IMA-B                 # filtra uma família
findata anbima ettj -d 2026-04-22           # curva zero numa data
findata anbima debentures -e Petrobras      # debêntures por emissor

# Registry: resolve CNPJ ↔ ticker ↔ nome em qualquer formato
findata registry lookup 33000167000101       # CNPJ raw → Petrobras (cvm + b3)
findata registry lookup "33.000.167/0001-01" # CNPJ com máscara → mesmo resultado
findata registry lookup PETR4                # ticker B3 → Petrobras
findata registry lookup "porto seguro"       # nome fragmento → SA + SUSEP entities
findata registry meta                        # build sha + counts por fonte

findata serve                   # sobe o servidor HTTP + MCP

Biblioteca Python

import asyncio
from findata.sources.bcb import sgs, ptax, focus
from findata.sources.ipea import get_series_values
from findata.registry import lookup

async def main() -> None:
    selic = await sgs.get_series_by_name("selic", n=5)
    print(selic)

    usd = await ptax.get_ptax_usd()  # hoje
    print(usd)

    ipca_expect = await focus.get_focus_annual("IPCA", top=3)
    print(ipca_expect)

    # Selic over mensal do IPEA (série desde 1974)
    hist = await get_series_values("BM12_TJOVER12", top=12)
    print(hist)

    # Registry — uma chamada resolve qualquer formato de identificador
    res = await lookup("PETR4")
    if res.entities:
        e = res.entities[0]
        print(f"{e.nome} (CNPJ {e.cnpj}, fontes={e.sources}, tickers={e.tickers})")

asyncio.run(main())

Registry — resolver CNPJ / ticker / nome

Um catálogo SQLite embarcado no wheel mapeia ~50.000 entidades brasileiras (CVM companies + funds + SUSEP) com enriquecimento opcional de tickers B3. Uma única query MATCH resolve:

from findata.registry import lookup

# Todos esses retornam Petrobras:
await lookup("33000167000101")        # CNPJ raw
await lookup("33.000.167/0001-01")    # CNPJ com máscara
await lookup("PETR4")                 # ticker B3
await lookup("9512")                  # cod_cvm
await lookup("petrobras")             # nome (fuzzy)

O Entity.rank (BM25) discrimina match exato (~ -10) de match difuso (~ -2), útil pra agentes / consumers decidirem confiança. A SQLite é rebuildada semanalmente via CI (.github/workflows/rebuild-registry.yml) e atualizada no PyPI a cada release.

API REST

findata serve                # http://localhost:8000
curl http://localhost:8000/bcb/series/name/selic?n=5
curl 'http://localhost:8000/bcb/focus/annual?indicator=IPCA&top=3'
curl 'http://localhost:8000/registry/lookup?q=33000167000101'
curl 'http://localhost:8000/registry/lookup?q=PETR4'
curl http://localhost:8000/docs     # Swagger UI
curl http://localhost:8000/redoc    # ReDoc

Servidor MCP

O endpoint MCP é gerado automaticamente a partir das rotas FastAPI. Qualquer cliente MCP (Claude Desktop, Cursor, Codex, Continue) consegue conectar em http://<host>:<port>/mcp e chamar todos os endpoints do findata como ferramentas.

// Exemplo de configuração de cliente MCP
{
  "mcpServers": {
    "findata-br": { "url": "http://localhost:8000/mcp" }
  }
}

Rodando como MCP server público

Quer compartilhar sua instância com a comunidade? O guia docs/DEPLOY_PUBLIC.md mostra como subir o findata-br no seu PC/WSL com Cloudflare Tunnel em ~20 min, custo R$ 0: HTTPS automático, URL fixa, DDoS protegido, rate-limit embutido. Quando a URL pública estiver no ar, qualquer pessoa pode apontar o Claude Desktop / Cursor / Codex pra ela e usar as 27 rotas como tools MCP.

  • Rate limit configurável via env: FINDATA_RATE_LIMIT_DEFAULT="60/minute;1000/day".
  • /health, /stats e Swagger em /docs — observabilidade out-of-the-box.
  • deploy/docker-compose.prod.yml e deploy/findata-br.service prontos pra produção.
        ▘▗   ▗
▀▌▛▘▛▌▌▌▌▜▘█▌▜▘▌▌▛▘▀▌
█▌▌ ▙▌▙▌▌▐▖▙▖▐▖▙▌▌ █▌
     ▌

    Arquitetura

 findata/
 ├─ http_client.py        ← cliente async httpx c/ cache, retry, URLs OData-safe
 ├─ banner.py             ← banner animado da CLI
 ├─ cli.py                ← app Typer
 ├─ api/
 │   ├─ app.py            ← FastAPI + mount do MCP
 │   └─ routers/          ← um router por fonte
 └─ sources/
     ├─ bcb/   (sgs, ptax, focus)
     ├─ cvm/   (companies, financials, funds, parser)
     ├─ ibge/  (indicators)
     ├─ ipea/  (series)
     ├─ tesouro/ (bonds)
     └─ b3/    (quotes)       ← opcional, atrás do extras

Cada fonte é um wrapper async tipado e enxuto sobre o endpoint público oficial. Todas compartilham http_client.get_json / get_bytes — assim pooling, retry e cache ficam centralizados em um único lugar.

▗     ▗
▜▘█▌▛▘▜▘█▌▛▘
▐▖▙▖▄▌▐▖▙▖▄▌

    Testes

pytest                       # unit + API rápidos (sem rede)
pytest -m integration        # bate nas APIs públicas reais
pytest -m ""                 # roda tudo

Os testes de integração são pulados por padrão — dependem de acesso à rede e do uptime dos terceiros. Atualmente o projeto tem 34 unit + 15 integration tests, todos verdes.

       ▌
▛▘▛▌▀▌▛▌▛▛▌▀▌▛▌
▌ ▙▌█▌▙▌▌▌▌█▌▙▌
             ▌

    Roadmap — próximos passos
  • Deploy — Dockerfile + docker-compose para servidor local em um comando.
  • CI/CD — GitHub Actions em cada push; publicação no PyPI em tag.
  • Rate limiting — middleware slowapi (para deploys públicos).
  • Observabilidade — logs JSON estruturados, /metrics (Prometheus), OpenTelemetry opcional.
  • ANBIMA — índices IMA, IMA-B, IDkA, IHFA.
  • B3 nativo — raspar os arquivos oficiais da B3 (índices, COTAHIST) pra soltar a dependência de yfinance.
  • Expansão IBGE — PNAD Contínua, produção industrial, comércio varejista, confiança.
  • Cache Redis — opt-in para cache distribuído em deploys multi-réplica.
  • SDK TypeScript — cliente gerado a partir do OpenAPI.
           ▘ ▌   ▌
▛▘▛▌▛▛▌▌▌▛▌▌▛▌▀▌▛▌█▌
▙▖▙▌▌▌▌▙▌▌▌▌▙▌█▌▙▌▙▖

    Comunidade

findata-br é open-source pra durar — MIT, sem CLA, sem adotar upstream comercial. O roadmap depende de quem usa: se você sentir falta de uma fonte (ANBIMA, SUSEP, BNDES, ...), abra uma issue usando o template "Nova fonte".

Qualquer desenvolvedor brasileiro interessado em dados financeiros abertos é convidado a hospedar sua própria instância pública e colaborar com PRs.

      ▗   ▘▌   ▘   ▌
▛▘▛▌▛▌▜▘▛▘▌▛▌▌▌▌▛▌▛▌▛▌
▙▖▙▌▌▌▐▖▌ ▌▙▌▙▌▌▌▌▙▌▙▌

    Contribuindo

Guia completo em CONTRIBUTING.md. TL;DR:

pip install -e '.[dev]'
bash scripts/git/install-hooks.sh   # habilita pre-commit + pre-push
ruff check src tests                # lint (core + AI guardrails)
mypy src                            # type check estrito
pytest                              # unit + API (sem rede)

Mantenha as mudanças tipadas (mypy --strict), linted (ruff check) e cobertas por testes. Para novas fontes, adicione testes de integração em tests/test_integration.py (marcador integration). Para o resto, prefira unit tests com respx que não batem em rede.

▜ ▘
▐ ▌▛▘█▌▛▌▛▘▀▌
▐▖▌▙▖▙▖▌▌▙▖█▌

    Licença

MIT — use como quiser.

Feito para o ecossistema de dados abertos do Brasil.

About

Open-source Brazilian financial data — REST API + MCP server + CLI. 10 fontes públicas (BCB, CVM, B3, Tesouro/SICONFI, ANBIMA, Receita, ANEEL, SUSEP, IBGE, IPEA). 117 testes, ruff + mypy strict, MIT.

Topics

python cli mcp brazil open-data brasil b3 financial-data cvm ipea tesouro-direto ipca selic bcb fastapi aneel susep anbima siconfi mcp-server

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v0.3.0 — Cross-source CNPJ resolver Latest
Apr 28, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages