Dados B3

Lista as companhias abertas brasileiras (ações da B3) com nome, código CVM e ticker principal. Use quando: "qual o ticker da Gerdau?"; "quais empresas da B3 vocês cobrem?". NÃO use para: fundo imobiliário → `fiis_ranking`; ETF → `etfs_ranking`; BDR → `bdr`; empresa que saiu da bolsa → `saiu_da_bolsa`. Fonte e fórmula: cadastro de companhias abertas da CVM ligado ao código de negociação da B3. Retorna: `empresas`: lista de {cd_cvm, nome, ticker} (ticker nulo quando a companhia não tem papel negociado); a contagem é o tamanho da lista. Vazio ou erro: não fica vazia; se o nome não aparecer, a companhia pode ter saído da bolsa (`saiu_da_bolsa`). Acesso: Gratuita, sem chave.

Takes no parameters.

ROE, ROIC, margens, crescimento da receita e dívida líquida/EBITDA de uma AÇÃO, ano a ano desde 2010. Use quando: "qual o ROE do Itaú em 2025?"; "como está a dívida líquida da Vale em relação ao EBITDA?"; "a margem da WEG cresceu nos últimos 5 anos?". NÃO use para: P/L, P/VP, EV/EBITDA → `multiplos`; ano corrente ou último trimestre → `trimestres`; receita, lucro e contas em R$ → `fatos_contabeis`; FII (P/VP, DY, vacância) → `fii`; Basileia e inadimplência de banco → `bancos`. Fonte e fórmula: DFP anual da CVM, versão vigente; ROE = lucro dos controladores ÷ PL médio dos controladores; ROIC = NOPAT ÷ capital investido médio; fórmula e conta CVM de cada um em `proveniencia`; memória de cálculo em /linhagem/TICKER/ANO/INDICADOR. Retorna: `indicadores`: linhas {ano, nome, valor (decimal: 0,15 = 15%), flag}; `proveniencia`; `citacao`. flag não nula = confie menos e leia a metodologia. Vazio ou erro: banco e seguradora vêm sem ROIC e EBITDA (não se aplicam ao plano de contas). Erro de código traz `sugestoes` e `tente_assim`; FII aponta para `fii`. Acesso: ABERTA: qualquer ticker, sem chave, um por vez (sem chave: 2000 consultas por hora e 20000 por dia, por endereço; com `chave_api` vale o limite da chave). Traz `citacao`: cite-a ao usar o número.

P/L, P/VP e EV/EBITDA de uma AÇÃO por ano, e P/L de 12 meses (TTM) por trimestre: está cara ou barata contra a própria história. Use quando: "qual o P/L da WEG hoje?"; "qual o P/VP do Banco do Brasil?"; "EV/EBITDA da Vale nos últimos anos". NÃO use para: ROE, ROIC, margem, dívida/EBITDA → `indicadores_anuais`; P/VP de fundo imobiliário → `fii`; resumo com comparação ao setor → `veredito`; filtrar várias ações por P/L → `screener`. Fonte e fórmula: preço do 1º pregão APÓS a publicação do balanço na CVM (sem informação futura) ÷ lucro, patrimônio ou EBITDA da DFP/ITR. Pelo método atual; o ponto-no-tempo numa data passada (`as_of`) só na REST, com chave. Retorna: `anuais` {ano, pl, pvp, ev_ebitda, data_preco, dt_receb, ressalvas}; `trimestrais` com pl_ttm; lpa, ações e valuation da rota REST. Vazio ou erro: valor nulo = lucro negativo ou dado ausente (veja `ressalvas`). Erro de código traz `sugestoes` e `tente_assim`. Acesso: ABERTA: qualquer ticker, sem chave, um por vez (sem chave: 2000 consultas por hora e 20000 por dia, por endereço; com `chave_api` vale o limite da chave). Traz `citacao`: cite-a ao usar o número.

Quanto uma AÇÃO pagou de dividendos e JCP: valor por ação, data-com, data de pagamento e dividend yield (DY) de 12 meses. Use quando: "quanto a Petrobras PN pagou de dividendos nos últimos 12 meses?"; "qual o DY do Itaú?"; "a Petz pagou dividendos antes de sair da bolsa?". NÃO use para: rendimento ou DY de FII (HGLG11, MXRF11) → `fii`; ranking das maiores pagadoras → `listas`; lista de quem saiu da bolsa → `saiu_da_bolsa`. Fonte e fórmula: proventos em dinheiro da B3 e da CVM, valor bruto (sem os 15% de IR do JCP); DY 12m = soma dos proventos com data-com nos últimos 365 dias ÷ último fechamento. Quem saiu da bolsa: Formulário de Referência (até ~2021) e IPE (desde 2024). Retorna: `proventos` {tipo, valor, data aprovação, data_com, preco_com, parcela, data_pagamento} de TODAS as classes (ON e PN): não some a lista; `resumo_anual` e DY 12 meses só da classe pedida, com o total do ano corrente até hoje e do ano anterior fechado; `citacao`. Delistada: `saiu_da_bolsa` e `cobertura.fontes`. Vazio ou erro: lista vazia de companhia listada = nenhum provento em dinheiro registrado no período, não erro. Erro com `saiu_da_bolsa` = ausência DESCONHECIDA, não "não pagou". Código de FII devolve `tente_assim` com `fii`. Acesso: ABERTA: qualquer ticker, sem chave, um por vez (sem chave: 2000 consultas por hora e 20000 por dia, por endereço; com `chave_api` vale o limite da chave). Traz `citacao`: cite-a ao usar o número.

Série DIÁRIA de preços de uma AÇÃO (abertura, máxima, mínima, fechamento, volume) num período. Use quando: "preço de fechamento da PETR4 em 2024"; "cotação diária da VALE3 desde 2020". NÃO use para: retorno, queda máxima ou volatilidade prontos → `desempenho`; quanto rendeu R$ 1.000 → `quanto_rendeu`; preço de FII → `fii`; preço de ETF → `etf`; preço de BDR → `bdr`; pontos do IBOV ou IFIX → `indice`. Fonte e fórmula: COTAHIST da B3, preço NÃO ajustado; os eventos societários do período vêm em `eventos`. Retorna: por padrão `colunas` + `linhas` (data, fechamento), do mais antigo ao mais recente; `campos` pede mais colunas; `campos="todos"` devolve `serie` com objetos (resposta grande); `limite` corta e avisa. Vazio ou erro: sem chave, AMOSTRA dos últimos 30 pregões com `aviso`. Erro de código: FII, ETF, BDR ou índice trazem `tente_assim` com a ferramenta certa; repita lá. Acesso: WEGE3 completa sem chave; demais tickers sem chave devolvem a amostra; com `chave_api` (grátis), a série inteira.

Quanto uma AÇÃO subiu ou caiu num período escolhido: retorno, retorno com dividendos, queda máxima e volatilidade, prontos. Use quando: "quanto a PETR4 rendeu de 2020 a 2024 com dividendos?"; "qual a maior queda da MGLU3 nos últimos 5 anos?"; "cruzamento de médias 21 x 100 valeu a pena na VALE3?". NÃO use para: R$ 1.000 em 1, 3, 5 ou 10 anos, ou FII/ETF → `quanto_rendeu`; a série diária → `precos`; benchmark IBOV/IFIX → `indice`; lucro, margem, endividamento → `veredito`. Fonte e fórmula: COTAHIST da B3, preço AJUSTADO por eventos societários; retorno total reinveste dividendos e JCP na data-ex; sem custos nem impostos. Retorna: `buy_and_hold` e `cruzamento_de_medias` {retorno_pct, retorno_total_pct, drawdown_maximo com datas, volatilidade}; `de`/`ate`; `premissas`. Vazio ou erro: padrão: últimos 5 anos. Período sem pregão suficiente devolve erro: amplie `de`/`ate`. Código de FII ou ETF traz `tente_assim` com `quanto_rendeu`. Acesso: Aberta, sem chave, qualquer ticker; `chave_api` é aceita e desnecessária.

Desempenho e pontos dos índices da B3 (IBOV, IFIX, SMLL, IDIV, IBXX): o benchmark para comparar uma ação ou um fundo. Use quando: "quanto o Ibovespa subiu em 2025?"; "qual a queda máxima do IFIX nos últimos 5 anos?"; "pontos diários do IBOV desde janeiro". NÃO use para: desempenho de uma ação → `desempenho`; ETF que replica o índice → `etf`. Fonte e fórmula: série da B3; índices de RETORNO TOTAL (a B3 reinveste os proventos nos pontos). Retorna: padrão: desempenho {retorno, queda máxima, volatilidade; comprar e manter e médias 21 x 100}, últimos 5 anos; `serie=True`: `colunas` (data, fechamento) e `linhas`; `codigo=""`: a lista. Vazio ou erro: código desconhecido: chame com `codigo=""` para a lista. ^BVSP vira IBOV. Série sem chave = amostra dos últimos 30 pregões. Acesso: Desempenho e lista abertos, sem chave; série inteira com `chave_api`.

Quantas linhas móveis e acessos de banda larga cada operadora tem, mês a mês (Vivo, TIM, Claro). Use quando: "quantos clientes de celular a Vivo tem?"; "participação da TIM na telefonia móvel". NÃO use para: balanço da VIVT3 ou TIMS3 → `fatos_contabeis`; tarifa de energia → `tarifas_energia`. Fonte e fórmula: dados abertos da Anatel (CC BY-ND 3.0 declarada pela Anatel, uso acertado com o órgão), somados por operadora; móvel sem M2M. Retorna: sem argumento: ranking por serviço {acessos, participacao_pct, variacao_12m_pct}; `servico` + `cnpj` (ou TOTAL): série mensal; `ticker` só quando o CNPJ é de empresa listada. Vazio ou erro: CNPJ sem dado devolve erro: use os 14 dígitos do ranking. O mês mais novo é preliminar. Acesso: Gratuita, sem chave.

Taxa e preço dos títulos do Tesouro Direto (Selic, Prefixado, IPCA+, Renda+, Educa+) por dia, desde 2004. Use quando: "quanto paga o Tesouro IPCA+ 2035 hoje?"; "taxa do Tesouro Prefixado em janeiro de 2024". NÃO use para: fundo de renda fixa → `fundos_investimento`; dividendos de ação → `dividendos`. Fonte e fórmula: Tesouro Transparente (ODbL), taxas indicativas da manhã, sem recálculo. Prefixado = taxa nominal a.a.; IPCA+, Renda+, Educa+ = taxa real; Selic = taxa sobre a Selic. Retorna: `taxas` {título, vencimento, taxa_compra_pct, taxa_venda_pct, pu_compra_rs, pu_venda_rs}, `dia_base`, `citacao`; `titulo` + `vencimento` = série diária recortada por `de`/`ate`. Vazio ou erro: título desconhecido devolve erro com as famílias válidas; `vencimento` exige `titulo`. Acesso: Gratuita, sem chave.

Quanto petróleo e gás cada operadora e cada campo produzem por dia, mês a mês (Petrobras, PRIO, Brava). Use quando: "quanto a Petrobras produziu de petróleo em junho de 2025?"; "maiores campos do pré-sal". NÃO use para: balanço ou dividendos da PETR4 ou PRIO3 → `fatos_contabeis`; preço da ação → `precos`. Fonte e fórmula: dados abertos da ANP (CC BY-ND 3.0 declarada, uso acertado com a ANP); média diária do mês: petróleo em bbl/dia, gás em mil m³/dia; participação e variação em 12 meses são contas nossas. Retorna: `producao` por operador ou campo {petroleo_bbl_dia, gas_mm3_dia, participacao_petroleo_pct}; com `cnpj`/`operador`/`campo`, série mensal; cada linha traz `fonte` e `escopo`. Vazio ou erro: de 2024 em diante a cobertura por campo é PARCIAL (`cobertura_manual` lista os meses que faltam). Nome não achado: tente `cnpj` ou o nome como está na ANP. Acesso: Gratuita, sem chave.

Tarifa residencial de energia de cada distribuidora (TUSD + TE em R$/MWh) e o último reajuste. Use quando: "qual a distribuidora com a energia mais cara?"; "quanto subiu a tarifa da Cemig no último reajuste?". NÃO use para: balanço da CMIG4 ou CPFE3 → `fatos_contabeis`; dividendos da elétrica → `dividendos`. Fonte e fórmula: dados abertos da ANEEL (ODbL), subgrupo B1 convencional, SEM tributos; variação contra o reajuste anterior é conta nossa. Retorna: `tarifas` {tusd_rs_mwh, te_rs_mwh, total_rs_mwh, variacao_pct}, `resumo` (mais barata, mediana, mais cara); `cnpj` = todas as vigências de uma distribuidora. Vazio ou erro: CNPJ sem dado devolve erro; a distribuidora costuma ser subsidiária, então `ticker` pode vir nulo. Acesso: Gratuita, sem chave.

Fundos de investimento da CVM (renda fixa, multimercado, ações): cota, patrimônio, cotistas e captação. Use quando: "quais fundos mais captaram este mês?"; "patrimônio do fundo Verde"; "série da cota do fundo CNPJ X". NÃO use para: fundo imobiliário listado (FII) → `fii`; ETF listado → `etf`; quais fundos têm uma ação → `fundos_da_acao`. Fonte e fórmula: Informe Diário da CVM (ODbL); captação líquida = captação − resgate; a variação mensal da cota é conta nossa, não a rentabilidade oficial. Retorna: sem argumento: `maiores_pl`, `maior_captacao_liquida`, `maior_resgate_liquido`; `cnpj`: o fundo com série de 13 meses; `busca`: por nome. Vazio ou erro: busca sem resultado: tire acento ou use o começo do CNPJ. `limite` vai de 1 a 500. Acesso: Gratuita, sem chave.

Quanto viraram R$ 1.000 numa ação, FII ou ETF em 1, 3, 5 e 10 anos, com e sem dividendos reinvestidos. Use quando: "quanto rendeu R$ 1.000 em ITUB4 nos últimos 5 anos?"; "o HGLG11 rendeu mais que o IFIX?"; "BOVA11 em 10 anos contra a Selic". NÃO use para: período escolhido (de/até) de uma ação → `desempenho`; só os dividendos → `dividendos`. Fonte e fórmula: COTAHIST da B3 e proventos registrados; janelas terminam no último fechamento; comparação com IBOV (IFIX para FII) e meta Selic; sem custos nem impostos. Mesmos números de /quanto-rendeu/TICKER. Retorna: `texto` em markdown com o valor final por janela, `url` e `citacao`. Vazio ou erro: janela sem histórico fica de fora do texto. Código desconhecido devolve erro; código antigo segue a troca sozinho. Acesso: Aberta, sem chave, qualquer ticker de ação, FII ou ETF.

Quais fundos de investimento têm uma AÇÃO na carteira, quanto têm e quem aumentou ou reduziu no mês. Use quando: "quais fundos têm PETR4?"; "os fundos venderam WEGE3 no último mês?". NÃO use para: dados de um fundo pelo CNPJ → `fundos_investimento`; carteira de um ETF → `etf`. Fonte e fórmula: CDA (Composição e Diversificação das Aplicações) entregue à CVM, bloco de ações, 13 meses (ODbL); a carteira sai depois do fim do mês. Retorna: maiores fundos por valor {fundo, valor, quantidade}, contadores e maiores movimentos de todos os fundos, e a data de referência. Vazio ou erro: lista vazia = nenhum fundo declarou a ação no mês de referência. `limite` vai de 1 a 500. Acesso: WEGE3 sem chave; demais ações exigem chave_api (grátis).

Basileia, inadimplência acima de 90 dias, carteira de crédito e lucro dos BANCOS listados, por trimestre. Use quando: "qual banco tem a maior inadimplência?"; "índice de Basileia do Itaú"; "compare BBAS3 e BBDC4". NÃO use para: ROE anual do banco → `indicadores_anuais`; P/L ou P/VP do banco → `multiplos`; dividendos do banco → `dividendos`. Fonte e fórmula: IF.data do Banco Central (conglomerado prudencial, ODbL), sem recálculo; inadimplência = divisão de duas linhas do próprio BC. Retorna: sem `ticker`: `bancos` (último trimestre de cada um em `ultimo`, ordem da carteira de crédito); com `ticker`: `serie` trimestral {basileia_pct, inadimplencia_90d_pct, carteira_credito_rs_mil}. Vazio ou erro: ticker que não é banco devolve erro: chame sem `ticker` para ver os bancos cobertos. Acesso: Gratuita, sem chave.

Quais empresas saíram da bolsa (deixaram de negociar na B3) em cada ano, com data e motivo. Use quando: "quais empresas saíram da bolsa em 2026?"; "a Petz saiu da B3? quando foi o último pregão?"; "quantas companhias fecharam o capital em 2025?". NÃO use para: dividendos que uma delistada pagou → `dividendos`; desdobramentos e cisões → `eventos`; fato relevante da saída → `fatos_relevantes`. Fonte e fórmula: COTAHIST da B3 (último pregão) e cadastro de companhias abertas da CVM (cancelamento, data e motivo); entram também as que pararam de negociar com registro ativo (fusão, OPA, mudança para fora); sem BDRs. Retorna: `por_ano` {ano: [companhias com código, nome, último pregão e, se cancelada, data e motivo]}, `contagem`, `criterio`, `fonte`, `pagina`, `citacao`. Vazio ou erro: só os 3 anos mais recentes; ano fora deles devolve erro com os anos disponíveis. Ano sem saída = lista vazia. Acesso: Gratuita, sem chave.

BDRs negociados na B3 (Apple AAPL34, Nvidia NVDC34, IVVB39): lista, preço em reais, rentabilidade e proventos. Use quando: "quais BDRs são mais negociados?"; "quanto rendeu AAPL34 em 5 anos?"; "BDR patrocinado ou não?". NÃO use para: ação brasileira → `precos`; ETF brasileiro → `etf`. Fonte e fórmula: cadastro e COTAHIST da B3; rentabilidade em reais, já com o câmbio; proventos por BDR em R$. Retorna: `ticker=""`: lista {ticker, tipo, último fechamento, liquidez}; com `ticker`: cadastro, último pregão, rentabilidade com e sem proventos (1 mês a 10 anos), proventos e desdobramentos; `serie=True`: `colunas`/`linhas`. Vazio ou erro: não tem o código da ação lá fora nem a proporção BDR:ação. Série sem chave = amostra de 30 pregões. Acesso: Lista e AAPL34 abertos; detalhe dos demais exige chave_api (grátis).

Desdobramentos, grupamentos, bonificações e cisões de uma ação, com a fonte e o que o preço confirmou. Use quando: "a WEG fez desdobramento?"; "quando foi o grupamento da MGLU3?". NÃO use para: dividendos e JCP → `dividendos`; troca de ticker no mês → `hoje`. Fonte e fórmula: eventos declarados pela B3 ou achados por nós no preço, cada um com `fonte`; eventos do mesmo dia formam uma operação (`efeito_liquido_do_dia`). Retorna: lista de eventos {data, tipo, fator, fonte, conferência pelo preço (confirmou, não distingue, discorda)}. Vazio ou erro: lista vazia = nenhum evento registrado. Empresa que saiu da bolsa responde com `saiu_da_bolsa`. Acesso: WEGE3 sem chave; demais tickers exigem chave_api (grátis).

Piotroski F-Score (0 a 9) e critério de Graham de uma ação, com cada critério auditável. Use quando: "qual o Piotroski da Vale?"; "a ação passa no critério de Graham?". NÃO use para: resumo descritivo da ação → `veredito`; os indicadores por ano → `indicadores_anuais`. Fonte e fórmula: DFP da CVM; Graham: P/L × P/VP ≤ 22,5. Banco não tem Piotroski. Retorna: os 9 critérios com valor e resultado, o total, e o cálculo de Graham. Vazio ou erro: banco devolve Piotroski nulo. Erro sem chave traz `como_resolver`. Acesso: WEGE3 sem chave; demais tickers exigem chave_api (grátis ou Pro).

Balanços REPUBLICADOS: quando a empresa mudou um número já entregue, as duas versões lado a lado. Use quando: "a Americanas reapresentou o balanço?"; "quais contas da empresa mudaram na republicação?". NÃO use para: as contas vigentes → `fatos_contabeis`; bandeira de confiança do resumo → `veredito`. Fonte e fórmula: DFP original × republicada na CVM, conta a conta; nunca corrigido em silêncio. Retorna: linhas {ano, conta CVM, valor antigo, valor novo, variação}. Vazio ou erro: lista vazia = nenhuma republicação com número alterado. Acesso: WEGE3 sem chave; demais tickers exigem chave_api (grátis ou Pro).

Receita, EBIT, lucro, patrimônio, dívida e caixa de uma AÇÃO em R$, por ano ou trimestre, com a conta CVM de cada número. Use quando: "qual foi a receita líquida e o lucro da WEG em 2025?"; "lucro do 2T da Petrobras"; "caixa da Magalu no último balanço". NÃO use para: ROE, margem, dívida/EBITDA já calculados → `indicadores_anuais`; versões republicadas → `reapresentacoes`; informe de FII → `fii`. Fonte e fórmula: DFP (anual) ou ITR (`trimestral=True`, 1T a 3T isolados) da CVM, versão vigente; `origem` = conta CVM exata. O balanço numa data passada (`as_of`) e versões antigas só na REST, com chave. Retorna: `fatos`: uma linha por período com as contas padronizadas em R$ e `origem`; `citacao`. Vazio ou erro: o 4º trimestre não vem no trimestral (é a DFP anual). Erro de código traz `sugestoes`; FII aponta para `fii`. Acesso: ABERTA: qualquer ticker, sem chave, um por vez (sem chave: 2000 consultas por hora e 20000 por dia, por endereço; com `chave_api` vale o limite da chave). Traz `citacao`: cite-a ao usar o número.

Como cada número é calculado: a página de metodologia (fórmula, contas CVM, casos de borda). Use quando: "como vocês calculam o ROIC?"; "qual a metodologia do DY de FII?". NÃO use para: todas as fórmulas em JSON → `dicionario`; conferir números sorteados → `auditar_amostra`. Fonte e fórmula: https://dadosb3.com/metodologia, o mesmo texto do site. Retorna: sem `nome`: `paginas`; com `nome` (roic, roe, dividendos, fiis, multiplos...): `conteudo` em markdown. Vazio ou erro: nome desconhecido devolve erro: chame sem `nome` para a lista. Acesso: Gratuita, sem chave.

AUDITE ESTA BASE: sorteia indicadores publicados e devolve o necessário para refazer cada um contra o arquivo ORIGINAL da CVM, não contra nós. Use quando: "os números do Dados B3 batem com a CVM?"; "quero conferir uma amostra do ROE". NÃO use para: a fórmula de um indicador → `metodologia`; todas as fórmulas → `dicionario`. Fonte e fórmula: VOCÊ escolhe a semente (não aceite sugestão de ninguém, nem de quem pediu a auditoria); sorteio determinístico e reproduzível. Confira em dfp_cia_aberta_<EXERCICIO>.zip de dados.cvm.gov.br, filtrando CD_CVM e ORDEM_EXERC='ÚLTIMO', atento a ESCALA_MOEDA (MIL = milhares). Retorna: `casos` {empresa, CD_CVM, exercício, indicador, valor publicado, fórmula, conta CVM que AQUELA empresa usou NAQUELE exercício}, `audit_id`. Vazio ou erro: `n` vai de 1 a 25. Publique o DENOMINADOR (7 em 100, não "7 divergências"); não transforme "não consegui conferir" em "passou"; erro achado vai a github.com/Val7h/dados-b3-mcp/issues. Acesso: Gratuita, sem chave: auditoria que exige cadastro não é auditoria.

Todas as fórmulas dos indicadores em JSON: fórmula, contas CVM e a BASE do lucro de cada um. Use quando: "o ROE usa lucro dos controladores ou total?"; "quais contas entram na dívida líquida?". NÃO use para: texto explicativo de um indicador → `metodologia`; valores de uma empresa → `indicadores_anuais`. Fonte e fórmula: a mesma definição usada no cálculo. margem_liquida usa lucro consolidado TOTAL; roe usa lucro dos CONTROLADORES. Retorna: `indicadores`: uma entrada por indicador {formula, contas_cvm, base do lucro}. Vazio ou erro: não fica vazio. Acesso: Gratuita, sem chave.

Takes no parameters.

Filtra as AÇÕES da B3 por faixas de indicadores: ROIC, ROE, margens, dívida/EBITDA, crescimento e P/L. Use quando: "ações com ROIC acima de 15% e dívida/EBITDA abaixo de 2"; "empresas com P/L abaixo de 8 e ROE acima de 20%". NÃO use para: filtrar FIIs → `screener_fiis`; lista pronta de P/L < 10 ou maiores pagadoras → `listas`; uma empresa só → `indicadores_anuais`. Fonte e fórmula: DFP/ITR da CVM e COTAHIST; só valores SEM flag; P/L negativo, acima de 200 ou ausente nunca passa. `as_of` = só o que era público naquele dia; universo das ativas hoje (viés de sobrevivência declarado). Retorna: linhas {ticker, indicadores, `multiplos` com dt_receb, data_preco e ressalvas}, `fora_do_filtro`; `recibo=True` congela num endereço permanente com sha256. Vazio ou erro: nenhuma linha = nenhuma ação passa: afrouxe um filtro. Chaves: indicador + _min/_max (roic, roe, margem_bruta, margem_ebit, margem_liquida, dl_ebitda, cresc_receita_1a, cresc_receita_5a_cagr, pl, pl_ttm). Acesso: Exige chave_api (grátis ou Pro).

Ranking dos fundos imobiliários (FIIs): menor P/VP, maior dividend yield 12 meses e medianas por segmento. Use quando: "quais FIIs pagam mais dividendos?"; "FIIs mais descontados (menor P/VP)"; "DY médio dos FIIs de logística". NÃO use para: um FII específico → `fii`; filtrar FIIs por faixas próprias → `screener_fiis`; lista pronta com data-base para citar → `listas`. Fonte e fórmula: informe mensal da CVM + COTAHIST; P/VP = preço do 1º pregão após o informe ÷ VP da cota; DY 12m = rendimentos de 12 meses ÷ preço; só fundos líquidos e valores sem flag. Retorna: `mais_descontados` e `maiores_dy` (15 cada) {ticker, nome, segmento, pvp, dy_12m}, `por_segmento`, `fundos_liquidos`, `citacao`. Vazio ou erro: erro "sendo construídos" = tente em minutos. Filtro em massa por faixas: `screener_fiis`, que exige chave. Acesso: ABERTA: qualquer ticker, sem chave, um por vez (sem chave: 2000 consultas por hora e 20000 por dia, por endereço; com `chave_api` vale o limite da chave). Traz `citacao`: cite-a ao usar o número.

Um fundo imobiliário (FII): dividend yield 12 meses, rendimentos pagos, P/VP, vacância e cotistas, pelo ticker (HGLG11, MXRF11, KNRI11). Use quando: "qual o DY dos últimos 12 meses do HGLG11?"; "o MXRF11 está acima ou abaixo do valor patrimonial?"; "quanto o KNRI11 pagou por cota no último mês?". NÃO use para: comparar ou listar muitos FIIs → `fiis_ranking`; filtrar FIIs por faixas → `screener_fiis`; dividendos de ação → `dividendos`; preço de ação → `precos`; R$ 1.000 em 1 a 10 anos → `quanto_rendeu`. Fonte e fórmula: informe mensal e trimestral da CVM + COTAHIST da B3; P/VP ponto-no-tempo = preço do 1º pregão após o informe ÷ VP da cota; DY 12m = rendimentos dos últimos 12 meses ÷ preço; vacância ponderada por área. Retorna: `cadastro`, `ultimo_informe` {cotistas, pl, competencia}, `pvp` (série), `dy_12m`, `proventos_recentes` (18), `vacancia` (só tijolo), `citacao`; `serie=True`: preço diário em `colunas`/`linhas`. Vazio ou erro: vacância vazia = fundo de papel (sem imóvel). FII desconhecido devolve erro: confira em `fiis_ranking`. Série sem chave = amostra de 30 pregões. Acesso: ABERTA: qualquer ticker, sem chave, um por vez (sem chave: 2000 consultas por hora e 20000 por dia, por endereço; com `chave_api` vale o limite da chave). Traz `citacao`: cite-a ao usar o número.

Resumo de uma AÇÃO em seis números: ganha dinheiro? está endividada? está cara contra o setor e a própria história? Use quando: "a Petrobras está cara?"; "resumo fundamentalista da WEGE3"; "a Vale está endividada?". NÃO use para: quanto a ação subiu ou caiu → `desempenho`; série anual completa → `indicadores_anuais`; Piotroski e Graham → `scores`. Fonte e fórmula: DFP da CVM e COTAHIST: margem líquida, ROIC, dívida líquida/EBITDA, P/L, P/VP, cada um contra a mediana do setor, a própria história e o universo; bandeira de confiança (reapresentação, atualidade, conferências). Retorna: `frase_topo` (até 25 palavras, sem adjetivo de julgamento), `perguntas`/`itens` com faixas, `bandeira` verde/amarelo/vermelho, `citacao`. Vazio ou erro: banco vem sem ROIC e EBITDA. Erro de código traz `sugestoes`. Acesso: Gratuita, sem chave, qualquer ticker. Descritivo: quem conclui é quem lê.

Filtra os fundos imobiliários (FIIs) por faixas de P/VP, dividend yield, segmento e cotistas. Use quando: "FIIs de logística com P/VP abaixo de 0,9"; "FIIs com DY acima de 10% e mais de 5.000 cotistas". NÃO use para: os rankings prontos sem filtro → `fiis_ranking`; um FII só → `fii`; filtrar ações → `screener`; lista pronta para citar → `listas`. Fonte e fórmula: informe mensal da CVM + COTAHIST; só P/VP e DY sem flag; piso de liquidez por cotistas. Retorna: `resultados` {ticker, nome, segmento, pvp, dy_12m, cotistas}, ordem de P/VP crescente, até 100; `n`. Vazio ou erro: nenhum resultado = afrouxe a faixa; segmento é match exato. Chaves válidas: pvp_min, pvp_max, dy_min, dy_max (decimal: 0,10 = 10%), segmento, cotistas_min. Acesso: Exige chave_api (grátis ou Pro).

Resultado TRIMESTRAL de uma AÇÃO: contas da ITR, margens e ROE de 12 meses, para o ano corrente. Use quando: "como foi o 2T da Petrobras?"; "a margem da WEG melhorou este ano?". NÃO use para: ano fechado → `indicadores_anuais`; contas em R$ por trimestre, abertas → `fatos_contabeis`. Fonte e fórmula: ITR da CVM (1T, 2T, 3T); o 4T não vem: o exercício fechado é da DFP e não derivamos 4T = anual − 9M. Retorna: série trimestral {contas, preço do trimestre, margem bruta, margem EBIT, margem líquida, ROE TTM}. Vazio ou erro: banco e seguradora recebem só margem líquida e ROE. Acesso: WEGE3 sem chave; demais exigem chave_api.

O que mudou no mercado brasileiro nos últimos 30 dias: balanços entregues, proventos aprovados, eventos e trocas de ticker. Use quando: "o que aconteceu com a empresa X esta semana?"; "quais empresas divulgaram balanço este mês?"; "trocas de ticker recentes". NÃO use para: texto de fato relevante → `fatos_relevantes`; histórico de dividendos → `dividendos`. Fonte e fórmula: CVM (entregas e reenvios), B3 (proventos, eventos, códigos) e informes de FII. Retorna: seções `balancos`, `reenvios`, `proventos`, `rendimentos_fii`, `informes_fii`, `eventos`, `trocas`, cada uma com `dados_ate`. Vazio ou erro: seção vazia = nada na janela; `dados_ate` antigo = fonte parada, não mercado parado. Acesso: Gratuita, sem chave.

Takes no parameters.

Os últimos Fatos Relevantes e Comunicados ao Mercado entregues à CVM, com o link do documento original. Use quando: "últimos fatos relevantes da Petrobras"; "alguma empresa anunciou fusão esta semana?". NÃO use para: resumo do mês com balanços e proventos → `hoje`; lista de quem saiu da bolsa → `saiu_da_bolsa`. Fonte e fórmula: dados abertos da CVM (ODbL), atualizados SEMANALMENTE, com a data e sem a hora; `frase` é só descritiva, sem leitura de impacto. Retorna: itens {companhia, assunto, data de entrega, protocolo, link CVM, frase}, `fonte`, `citacao`. Vazio ou erro: lista vazia = nenhum documento da categoria no arquivo; troque `categoria` ou aumente `limite`. Acesso: Gratuita, sem chave.

Cobertura e frescor da base: contagens, último pregão e última coleta. Use quando: "até que data vão os preços?"; "quantas empresas a base tem?". NÃO use para: como um número é calculado → `metodologia`. Fonte e fórmula: o próprio banco servido. Retorna: `data_version`, `contagens`, `cobertura_de_preco`, `ultima_ingestao` e o estado de cada fonte. Vazio ou erro: `avisos` diz se a base servida está atrasada. Acesso: Gratuita, sem chave.

Takes no parameters.

Ranking dos ETFs da B3: mais negociados, maior patrimônio, ágio e deságio, retorno 12 meses e menor taxa efetiva. Use quando: "qual ETF tem a menor taxa?"; "ETFs mais negociados da B3"; "algum ETF negocia com deságio?". NÃO use para: um ETF específico (BOVA11, IVVB11) → `etf`; BDR de ETF → `bdr`. Fonte e fórmula: informe diário do FNET e COTAHIST; ágio = preço ÷ cota do MESMO dia; taxa EFETIVA = despesa do balancete ÷ PL médio, anualizada; só ETF com liquidez > R$ 1 mi/dia em ágio, retorno e taxa. Retorna: listas `mais_negociados`, `maior_patrimonio`, `maior_desagio`, `maior_agio`, `retorno_12m_pela_cota`, `menor_taxa_efetiva`, `por_tipo`, `dados_ate`. Vazio ou erro: erro "sendo construídos" = tente em minutos. Acesso: Gratuita, sem chave.

Takes no parameters.

Um ETF da B3 (BOVA11, IVVB11, SMAL11): ágio ou deságio sobre a cota, taxa efetiva, carteira e retornos. Use quando: "qual o ágio do BOVA11?"; "o que tem na carteira do IVVB11?"; "preço diário do SMAL11". NÃO use para: comparar vários ETFs → `etfs_ranking`; R$ 1.000 em 1 a 10 anos → `quanto_rendeu`. Fonte e fórmula: cadastro CVM + B3, informe diário do FNET, balancete (taxa EFETIVA, não a nominal), carteira da CVM; retorno pela cota = retorno total. Retorna: `cadastro`, `ultimo_informe`, `agio_30_pregoes`, `taxa_efetiva_mensal`, `carteira` (10 maiores, sobreposição), `retornos_pela_cota`, `retornos_pelo_preco`; `serie=True`: `colunas`/`linhas`. Vazio ou erro: ETF desconhecido devolve erro: veja `etfs_ranking`. Série sem chave = amostra de 30 pregões. Acesso: BOVA11 sem chave; demais exigem chave_api (grátis ou Pro).

A lista pronta com data-base: maiores pagadoras de dividendos, ações com P/L abaixo de 10 e FIIs de maior rendimento. Use quando: "quais ações mais pagaram dividendos nos últimos 12 meses?"; "ações com P/L abaixo de 10"; "FIIs que mais pagam". NÃO use para: filtro próprio de ações → `screener`; filtro próprio de FIIs → `screener_fiis`; rankings de P/VP de FII → `fiis_ranking`; dividendos de uma ação → `dividendos`. Fonte e fórmula: a mesma conta das páginas dadosb3.com/listas: liquidez mínima de R$ 5 mi/dia em 63 pregões, teto de 30% de DY marcado, uma classe por empresa; FIIs com 5.000 cotistas. Retorna: nome, data-base, critério, linhas {ticker, valores}, fonte e `source_url` para citar. Vazio ou erro: `lista` vazia devolve o catálogo; nome desconhecido devolve erro com as válidas (dividendos, pl, fiis). Acesso: ABERTA: qualquer ticker, sem chave, um por vez (sem chave: 2000 consultas por hora e 20000 por dia, por endereço; com `chave_api` vale o limite da chave). Traz `citacao`: cite-a ao usar o número.