bolsai vs yfinance: dados da B3 em Python sem quebrar em 2026

Antes de comparar, o critério: este texto não trata o yfinance como ruim. Para muitos casos ele é a escolha certa, e milhares de notebooks de estudo comprovam isso. O ponto é entender onde a natureza da ferramenta (uma biblioteca não oficial que consome o Yahoo Finance) cria atrito específico para quem trabalha com a bolsa brasileira, e quando esse atrito justifica migrar para uma API oficial. Quem busca dados fundamentalistas python b3 confiáveis costuma esbarrar exatamente nesses limites.

O que é o yfinance e onde ele brilha

O yfinance é uma biblioteca Python gratuita e de código aberto que consome dados do Yahoo Finance. Ela é global (cobre milhares de ativos em dezenas de bolsas), simples de instalar e ideal para prototipagem. Para acessar um ticker brasileiro, é preciso adicionar o sufixo .SA (de São Paulo): PETR4.SA, VALE3.SA, ITUB4.SA. Os pontos onde o yfinance genuinamente se destaca:

• Gratuito e sem chave: não exige cadastro nem API key para começar.
• Global: ações dos EUA, Europa, Ásia, índices, ETFs e câmbio no mesmo pacote.
• Ótimo histórico OHLCV: séries longas de abertura, máxima, mínima, fechamento e volume, com ajuste por proventos.
• Fácil para protótipos e backtests: integra direto com pandas, o padrão de fato para análise de dados.

Para um estudante testando uma estratégia, um pesquisador puxando índices globais ou alguém montando o primeiro notebook, o yfinance resolve com custo zero. Nada abaixo tira o mérito desses casos.

Onde o yfinance quebra para a B3

As limitações do yfinance com ações brasileiras não aparecem no primeiro notebook. Elas aparecem quando o projeto cresce e passa a depender de fundamentos, dividendos completos ou estabilidade. São problemas conhecidos por quem já tentou usar o yfinance b3 em algo mais sério que um estudo:

• Fundamentos escassos ou ausentes: para empresas brasileiras, os campos de fundamentos (P/L, ROE, margens, endividamento) vêm incompletos, desatualizados ou vazios com frequência. O Yahoo não trata a CVM como fonte primária.
• Lacunas em dividendos: o histórico de proventos de papéis da B3 costuma ter buracos, e a distinção entre dividendo e JCP, importante no Brasil por causa do imposto, não é explícita.
• Tickers descontinuados ou renomeados somem: quando uma empresa muda de ticker, incorpora ou sai da bolsa, o histórico no Yahoo pode desaparecer, o que introduz viés de sobrevivência em backtests.
• É não oficial e frágil: o yfinance depende de endpoints internos do Yahoo. Quando o Yahoo muda algo, a biblioteca quebra até a comunidade corrigir. Uso intenso pode levar a rate limit ou bloqueio de IP.
• Sem demonstrações da CVM: não há acesso às contas brutas de DRE, balanço e fluxo de caixa em padrão brasileiro.
• Sem profundidade em FIIs: fundos imobiliários, uma classe central para o investidor brasileiro, não têm P/VP, DY e vacância tratados como na B3.

O denominador comum é que o yfinance é uma camada global e não oficial sobre o Yahoo, não uma fonte pensada para a B3. Para protótipos, o custo dessas limitações é baixo. Para produção, análise fundamentalista ou um produto, o custo sobe rápido.

Comparação lado a lado

A tabela abaixo resume as diferenças estruturais entre a biblioteca yfinance e a API bolsai para o caso específico de ações brasileiras, com base no comportamento observado de cada uma em julho de 2026.

Nenhuma coluna é toda verde, e isso é honesto. O yfinance vence em custo e cobertura global; a bolsai vence em profundidade da B3, confiabilidade e uso em produção. A documentação completa da bolsai está em /docs. Para um panorama mais amplo com outras fontes, o comparativo API da B3: alternativas e como escolher ajuda a organizar os critérios.

Cotação em Python: yfinance vs bolsai

O caso mais simples é puxar o histórico de preços de PETR4. Com o yfinance, o ticker precisa do sufixo .SA. Com a bolsai, o ticker é o código puro da B3 e a chave vai no header. As duas devolvem dados que entram direto em pandas.

import yfinance as yf

# B3 exige o sufixo .SA
petr = yf.Ticker("PETR4.SA")
hist = petr.history(period="1mo")

print(hist["Close"].tail(1))
# Funciona bem para OHLCV.
# Mas pode falhar se o Yahoo
# mudar ou aplicar rate limit.

import requests

API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

r = requests.get(
    f"{BASE}/stocks/PETR4/history",
    headers=HEADERS,
    params={"limit": 21},
)
d = r.json()
print(d["data"][0]["close"])

Para OHLCV puro, os dois entregam o resultado. A diferença aparece na confiabilidade: a chamada da bolsai atinge um contrato de API documentado e versionado, enquanto o yfinance depende do Yahoo continuar respondendo no formato esperado. Para consumir o histórico de preços da B3 em produção, o post dados históricos de ações da B3 via API mostra o padrão completo, incluindo ajuste por splits e exportação em CSV.

Fundamentos: o ponto onde a diferença é gritante

É aqui que a comparação deixa de ser sobre estilo. Com o yfinance, tentar ler fundamentos de uma empresa brasileira via .info costuma devolver campos vazios, desatualizados ou inconsistentes, porque o Yahoo não trata a CVM como fonte. Com a bolsai, uma única chamada devolve um objeto plano com os 27 indicadores calculados a partir das demonstrações oficiais.

import yfinance as yf

info = yf.Ticker("ITUB4.SA").info

# Campos brasileiros costumam vir
# vazios, defasados ou ausentes:
print(info.get("trailingPE"))
print(info.get("returnOnEquity"))
# None ou valor inconsistente

import requests

r = requests.get(
    f"{BASE}/fundamentals/ITUB4",
    headers=HEADERS,
)
d = r.json()

print(d["pl"], d["pvp"])
print(d["roe"], d["net_margin"])
print(d["reference_date"])

Os valores acima são ilustrativos, apenas para mostrar o formato: os números reais vêm da chamada. Sobre a precisão, a bolsai documenta abertamente como cada indicador é calculado. O lucro líquido TTM usa a conta CVM 3.11 (total consolidado), consistente com a metodologia do Fundamentus; o EBIT é calculado de forma limpa como Resultado Bruto menos SG&A; para bancos, o patrimônio usa as contas 2.07 e 2.08. Esse rigor se traduz em 96% de acurácia em relação ao Fundamentus para dados recentes (DFP 2025). Além dos indicadores, o endpoint /financials/{ticker} entrega as contas CVM brutas, e /fundamentals/{ticker}/history a série trimestral de cerca de 11 anos. Quem quiser o detalhe da metodologia pode ler o comparativo alternativa ao Fundamentus com API oficial.

O problema do não oficial em produção

Uma biblioteca não oficial é excelente para prototipar e arriscada para produção. O yfinance não tem um contrato público com o Yahoo: ele consome endpoints internos que podem mudar de formato, de rota ou apertar o rate limit sem aviso. Na prática, isso significa que um pipeline que roda todo dia pode parar de funcionar de uma hora para outra, até que a comunidade publique uma correção. Para um estudo, é um inconveniente; para um produto ou um relatório automático que outras pessoas dependem, é um risco operacional real.

Uma API oficial e documentada resolve isso por design. A bolsai expõe um contrato estável em /docs, com um plano de limites conhecidos, autenticação por X-API-Key e respostas versionadas. Os dados vêm de fontes oficiais (B3, CVM e BCB) e são atualizados ao fim do dia, após o fechamento do pregão, às 20:30 BRT. Vale a nota honesta: por serem de fim de dia, os dados da bolsai não servem para day trade ou monitoramento intradiário. Eles são adequados para análise fundamentalista, screening, backtest e carteiras de longo prazo, que é justamente onde a confiabilidade importa mais.

Integração com IA: o servidor MCP da bolsai

Uma diferença que não existe no mundo das bibliotecas: a bolsai publica um servidor MCP (Model Context Protocol) oficial. O MCP é um padrão aberto que permite a agentes de IA como Claude Desktop, Cursor e Zed descobrirem e chamarem ferramentas externas de forma estruturada. Com o servidor da bolsai instalado, o agente consulta cotações, fundamentos e dividendos sozinho, sem glue code. Uma biblioteca Python como o yfinance não oferece esse tipo de superfície para um agente conversar.

# Instala o servidor MCP da bolsai
pip install bolsai-mcp

# Em claude_desktop_config.json:
{
  "mcpServers": {
    "bolsai": {
      "command": "uvx",
      "args": ["bolsai-mcp"],
      "env": { "BOLSAI_API_KEY": "sua_chave" }
    }
  }
}

Depois disso, você pode pedir ao Claude "compare o P/L e o ROE de ITUB4, BBAS3 e BBDC4" ou "liste bancos com dividend yield acima de 6%", e ele busca os dados da bolsai para responder. O guia completo, com exemplos para Cursor e Zed, está em /mcp.

Quando usar cada uma

Todo comparativo útil termina com uma decisão por caso de uso. Abaixo, uma divisão honesta, reconhecendo que projetos reais frequentemente usam os dois.

Escolha o yfinance quando

• Você está prototipando, estudando ou montando um notebook exploratório.
• O universo inclui ativos globais (ações dos EUA, índices, ETFs internacionais).
• O foco é OHLCV e o custo precisa ser zero.
• A eventual quebra da biblioteca não compromete nada importante.

Escolha a bolsai quando

• Você precisa de fundamentos confiáveis da B3, calculados a partir da CVM.
• O projeto depende das demonstrações financeiras brutas ou do histórico trimestral.
• Dividendos completos, com distinção entre dividendo e JCP, importam.
• FIIs fazem parte do universo, com P/VP, DY e vacância.
• O código roda em produção e não pode quebrar quando o Yahoo muda.
• Um agente de IA precisa consultar os dados via MCP.

Combine os dois quando

Muitos projetos reais tiram o melhor de cada um. O yfinance cobre os ativos globais e serve para prototipar rápido; a bolsai entrega os dados sérios da B3 (fundamentos, demonstrações, dividendos, FIIs) para a parte que vai para produção. Como o yfinance devolve DataFrames e a bolsai devolve JSON e CSV, é trivial combiná-los num mesmo script pandas. Quem já decidiu trocar a fonte pode seguir o passo a passo em como migrar do yfinance para uma API da B3, com código antes e depois. Para uma comparação entre APIs REST focadas na B3, vale ler o comparativo bolsai vs brapi.

Veredito

O yfinance é uma ferramenta excelente para o que se propõe: acesso gratuito e global a preços, perfeito para prototipar e estudar. Para ações brasileiras em contexto sério, porém, a natureza não oficial e a ausência de fundamentos, demonstrações e FIIs cobram um preço. A bolsai não tenta substituir o yfinance no mundo global; ela resolve a B3 com profundidade e confiabilidade, com fundamentos calculados, dados da CVM, dividendos completos, FIIs e um contrato de API estável. Se a sua pergunta é "quero um preço rápido de qualquer ativo do mundo", o yfinance responde. Se é "preciso analisar empresas da B3 a sério, em produção ou com IA", a bolsai foi construída para isso. E os dois convivem bem.

Perguntas frequentes

yfinance funciona com ações brasileiras da B3?

Funciona, com o sufixo .SA no ticker (por exemplo PETR4.SA). O histórico de preços OHLCV costuma ser bom e a biblioteca é gratuita e global. As limitações aparecem na B3: os fundamentos de empresas brasileiras são escassos ou ausentes, há lacunas em dividendos, tickers descontinuados ou renomeados desaparecem, não há demonstrações da CVM e não há profundidade em FIIs. Como é uma biblioteca não oficial que consome o Yahoo Finance, ela também quebra quando o Yahoo muda algo e pode sofrer rate limit ou bloqueio.

Qual a diferença entre yfinance e a bolsai?

O yfinance é uma biblioteca Python gratuita que consome dados do Yahoo Finance, ótima para protótipos rápidos e dados globais. A bolsai é uma API REST oficial focada na B3, com 27 indicadores fundamentalistas calculados com TTM, histórico trimestral de cerca de 11 anos, contas CVM brutas, dividendos históricos, FIIs, screener e servidor MCP. O yfinance brilha em OHLCV global e custo zero; a bolsai brilha em fundamentos confiáveis da B3, estabilidade de contrato e uso em produção.

Por que o yfinance quebra às vezes?

Porque é uma biblioteca não oficial que depende de endpoints internos do Yahoo Finance, que não são um contrato público. Quando o Yahoo muda o formato de resposta, altera rotas ou aperta o rate limit, o yfinance para de funcionar até a comunidade publicar uma correção. Em produção isso é um risco: seu pipeline pode parar sem aviso. Uma API oficial e documentada como a bolsai oferece um contrato estável e um plano com limites conhecidos.

Posso usar yfinance e a bolsai juntos?

Sim. Um fluxo comum usa o yfinance para prototipar e para dados de ativos globais (índices, ações dos EUA) e a bolsai para os dados confiáveis da B3: fundamentos calculados, demonstrações CVM, dividendos históricos, FIIs e uso em produção. Como os dois retornam dados em formato tabular ou JSON, é fácil combiná-los num mesmo script pandas. A bolsai também exporta CSV direto, o que simplifica a integração com planilhas.

Leia também

Referências

• github.com/ranaroussi/yfinance: repositório oficial da biblioteca yfinance.
• b3.com.br: fonte primária de cotações, COTAHIST e eventos corporativos.
• gov.br/cvm: Comissão de Valores Mobiliários, fonte das demonstrações financeiras.
• Documentação da bolsai: endpoints, parâmetros, exemplos e limites.

Este conteúdo é educativo e não constitui recomendação de investimento. O comportamento do yfinance descrito reflete observação pública da biblioteca e da sua dependência do Yahoo Finance em julho de 2026 e pode mudar a qualquer momento; consulte o repositório oficial antes de decisões de arquitetura. Os planos e limites da bolsai citados também podem ser atualizados. Os dados da bolsai são de fim de dia (20:30 BRT), não em tempo real.