Metadata-Version: 2.4
Name: dadosb3
Version: 0.1.0
Summary: Cliente Python da API Dados B3: fundamentos auditáveis de ações, FIIs e ETFs da bolsa brasileira (CVM/B3), com metodologia pública.
Author-email: Dados B3 <contato@dadosb3.com>
License-Expression: MIT
Project-URL: Homepage, https://dadosb3.com
Project-URL: Documentation, https://dadosb3.com/api
Project-URL: Methodology, https://dadosb3.com/metodologia
Project-URL: MCP connector, https://github.com/Val7h/dados-b3-mcp
Keywords: b3,bovespa,cvm,fundamentos,ações,fii,etf,brasil,finance,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Dynamic: license-file

# dadosb3

Cliente Python da [API Dados B3](https://dadosb3.com): fundamentos **auditáveis**
das companhias abertas brasileiras (2010–hoje), fundos imobiliários (FIIs) e
ETFs, com metodologia pública. Cada número carrega a conta CVM de origem; os
múltiplos são ponto-no-tempo (preço do 1º pregão a partir da chegada do balanço
à CVM); nada é publicado sem a bateria de invariantes passar.

```bash
pip install dadosb3
```

```python
from dadosb3 import DadosB3

api = DadosB3()                        # sem chave: WEGE3, BOVA11, MXRF11, rankings de ETF, /hoje, /saude
api.indicadores("WEGE3")["anos"]       # ROE, ROIC, margens... com a conta CVM de cada número
api.multiplos("WEGE3")                 # P/L, P/VP, EV/EBITDA ponto-no-tempo
api.etf("BOVA11")                      # cota diária, ágio/deságio, taxa efetiva, carteira
api.auditar_amostra(semente=4242)      # sorteie a SUA amostra e confira contra a CVM

api = DadosB3(chave="sua-chave")       # ou DADOS_B3_API_KEY no ambiente
api.screener(roic_min=0.15, dl_ebitda_max=2, ano=2024)
api.fiis_screener(pvp_max=0.9, dy_min=0.10)
```

Chave grátis (200 consultas/dia, sem cartão) ou Pro em
[dadosb3.com/assinar](https://dadosb3.com/assinar). Documentação da API em
[dadosb3.com/api](https://dadosb3.com/api); metodologia em
[dadosb3.com/metodologia](https://dadosb3.com/metodologia); para quem é (e para
quem não é) em [dadosb3.com/para-quem](https://dadosb3.com/para-quem).

## Métodos

| Método | Rota | Chave? |
|---|---|---|
| `empresas()` | `/empresas` | não |
| `indicadores(t)`, `multiplos(t)`, `fatos(t)`, `dividendos(t)`, `scores(t)`, `reapresentacoes(t)`, `trimestres(t)` | `/empresas/{t}/...` | WEGE3 não; demais sim |
| `screener(ano=, **faixas)` | `/screener` | sim |
| `fii(t)` | `/fiis/{t}` | MXRF11 não; demais sim |
| `fiis_ranking()`, `fiis_screener(**faixas)` | `/fiis`, `/fiis/screener` | sim |
| `etfs_ranking()` | `/etfs` | não |
| `etf(t)` | `/etfs/{t}` | BOVA11 não; demais sim |
| `hoje()`, `saude()`, `dicionario()` | `/hoje`, `/saude`, `/dicionario` | não |
| `auditar_amostra(semente, n=25)` | `/auditoria/amostra/{semente}/{n}` | não |

Erros: `ChaveNecessaria` (401), `NaoEncontrado` (404), `ErroDadosB3` (demais),
todos com `.status` e `.detalhe` (o corpo da resposta da API).

## Limites, ditos antes

Preço só de fim de dia (COTAHIST); sem tratamento de viés de sobrevivência
(companhia que saiu da bolsa não está na base); sem composição histórica de
índice; a base começa em 2010. A lista completa está em
[dadosb3.com/o-que-nao-resolvemos](https://dadosb3.com/o-que-nao-resolvemos).

Não é recomendação de investimento. Fontes: CVM (dados abertos, ODbL) e B3
(COTAHIST). Projeto independente, não afiliado à B3 nem à CVM. Licença deste
cliente: MIT. Conector MCP: [Val7h/dados-b3-mcp](https://github.com/Val7h/dados-b3-mcp).
