DEV Community

RAFAELDCOELHO
RAFAELDCOELHO

Posted on

Construí uma biblioteca Python que unifica APIs de mercado financeiro brasileiro

#python #opensource #finance #braziliandev

O problema

Todo dev brasileiro que já tentou construir algo em fintech, trading, análise macro ou planejamento financeiro passou por isso:

  • A API do Bacen (SGS) funciona, mas retorna dados em formato exótico.
  • O SIDRA do IBGE tem a melhor base de dados econômicos do país, mas a estrutura aninhada da resposta é de machucar os olhos.
  • O Tesouro Direto não tem API oficial estável — o único endpoint JSON que existia foi descontinuado em 2025 e hoje está atrás de Cloudflare.
  • Para cotações da B3, a investpy está deprecated e a yfinance não cobre ativos brasileiros direito.

Cada projeto financeiro brasileiro começa reinventando parser de XML, scraper de CSV e normalização de tickers. É um custo silencioso que ninguém quantifica.

A solução

Publiquei esta semana a brazilfi — um SDK Python que unifica essas fontes em uma API única, tipada e testada.

pip install brazilfi
Enter fullscreen mode Exit fullscreen mode 
from brazilfi import Bacen, IBGE, TesouroDireto, B3

# Macro: SELIC dos últimos 30 dias
Bacen().selic(last=30).to_dataframe()

# PIB trimestral (com a classificação correta do SIDRA aplicada automaticamente)
IBGE().pib(last=8).to_dataframe()

# Títulos do Tesouro Direto disponíveis agora
TesouroDireto().available_dataframe()

# Cotações B3 em tempo real
B3().quote(["PETR4", "VALE3", "ITUB4"])
Enter fullscreen mode Exit fullscreen mode

Tudo que retorna são DataFrames pandas ou modelos Pydantic v2 tipados. Tudo que precisa autenticar, não precisa — são todas APIs públicas.

Decisões técnicas que importaram

1. Modelos Pydantic v2 em vez de dicts. DataFrames são ótimos pra análise, mas péssimos pra contratos de API. Pydantic dá autocomplete no IDE, validação e serialização de graça.

2. Async-ready, sync por padrão. O HttpClient interno tem get() e aget(). A API pública é síncrona pra quem quer simplicidade, mas async está pronto pra quem vai paralelizar (ex: buscar 50 séries de uma vez).

3. O Tesouro Direto é uma saga. O endpoint JSON oficial foi descontinuado em 2025. Headers realistas de Chrome não passam pelo Cloudflare. A solução foi usar o CSV oficial do Tesouro Transparente (dados abertos gov.br): dados D-1 em vez de tempo real, mas 100% estável e oficial.

4. B3 via BrAPI.dev. Sem API oficial pública e gratuita da B3. A BrAPI.dev oferece free tier com 4 tickers principais (PETR4, VALE3, ITUB4, MGLU3) sem cadastro, e tier gratuito completo com registro. A lib detecta automaticamente se você tem token e falha com mensagem clara caso contrário.

5. CI desde o primeiro commit. GitHub Actions rodando ruff + mypy strict + pytest em Python 3.11 e 3.12 a cada push. Commit não entra em main sem verde. 36 testes passando, 76% de cobertura.

6. Trusted Publishing. Próximas releases para o PyPI são automáticas via GitHub Actions OIDC — zero tokens manuais, zero risco de vazamento de credencial.

Exemplo de uso real: rendimento real dos Prefixados 

from brazilfi import TesouroDireto, IBGE

prefixados = [b for b in TesouroDireto().available() if b.bond_type == "LTN"]
ipca_12m = float(IBGE().ipca(last=12).to_dataframe().sum().iloc[0])

for bond in sorted(prefixados, key=lambda b: b.maturity):
    real = float(bond.buy_rate) - ipca_12m
    print(f"{bond.name}: {bond.buy_rate}% nominal, {real:.2f}% real")
Enter fullscreen mode Exit fullscreen mode

Em 8 linhas: comparador de renda fixa real que normalmente exigiria navegar 3 sites diferentes.

Status atual (v0.3.0)

  • ✅ Bacen (SELIC, CDI, IPCA, dólar + qualquer série SGS)
  • ✅ IBGE (PIB, PNAD, IPCA, população + qualquer agregado SIDRA)
  • ✅ Tesouro Direto (títulos ativos + histórico completo)
  • ✅ B3 (cotações, histórico OHLCV, listagem via BrAPI.dev)
  • 🔜 CVM (fundos, DFPs)
  • 🔜 ANBIMA (curvas IMA, debêntures)

Há issues marcadas como good first issue pra quem quiser contribuir — adicionar IGP-M, suporte a UFs/municípios no IBGE, curva IMA-B da ANBIMA, etc.

Links:

Se você já passou raiva com essas APIs, testa e me conta nos comentários. Feedback técnico também super bem-vindo — a lib ainda é nova e tem decisões de design em aberto.

Top comments (0)