Cotações históricas da B3 (COTAHIST)¶
Resumo¶
A série histórica de cotações da B3 traz o histórico de preços dos títulos negociados na bolsa desde 1986, na moeda e na forma de cotação da época, sem ajuste para inflação nem para proventos (dividendos, bonificações, direitos de subscrição). Cada linha é um papel-mercado em um pregão: ação à vista, fracionário, opção, termo, fundo imobiliário, BDR e outros. Serve para reconstituir preços, volumes e liquidez ao longo do tempo.
Ficha técnica¶
| Campo | Valor |
|---|---|
| Dataset | b3/cotacaohistorica |
| Órgão | B3 S.A. - Brasil, Bolsa, Balcão |
| Página oficial | https://www.b3.com.br/pt_br/market-data-e-indices/servicos-de-dados/market-data/historico/mercado-a-vista/cotacoes-historicas/ |
| Licença | Não há licença aberta declarada. A página da série histórica diz que os dados são de propriedade exclusiva da B3, destinados estritamente à consulta informativa conforme os Termos e Condições de Uso (https://www.b3.com.br/pt_br/termos-de-uso-e-protecao-de-dados/termos-de-uso/), e veda a coleta automatizada |
| Periodicidade | arquivo anual, regerado ao longo do ano corrente; a página não declara a frequência |
| Cobertura | 1986-01 a em-curso |
| Unidade (uma linha) | um papel-mercado em um pregão (registro 01 do arquivo) |
| Granularidade | espacial: nacional (bolsa); temporal: dia de pregão |
| Formato bruto | ZIP anual com TXT de largura fixa, 245 bytes por linha, Latin-1 (alguns registros recentes em UTF-8); registros 00, 01 e 99 |
| Estado no lake | convertido |
| Partições | ano |
| Chave | — |
| Colunas | 26 |
| Unidades de medida | tipreg: código do tipo de registro (sempre 1); tipo_mercado_id: código (tabela TPMERC); preco_abertura: moeda de simbolo_moeda, por unidade de cotação (veja fator_cotacao); preco_maximo: moeda de simbolo_moeda, por unidade de cotação; preco_minimo: moeda de simbolo_moeda, por unidade de cotação; preco_medio: moeda de simbolo_moeda, por unidade de cotação; preco_ultimo_negocio: moeda de simbolo_moeda, por unidade de cotação; preco_melhor_oferta_compra: moeda de simbolo_moeda, por unidade de cotação; preco_melhor_oferta_venda: moeda de simbolo_moeda, por unidade de cotação; quantidade_negocios: negócios; quantidade_titulos_negociados: títulos; volume_negociado: moeda de simbolo_moeda; preco_exercicio: moeda de simbolo_moeda (opções) ou valor do contrato (termo secundário); indice_correcao_id: código (tabela INDOPC); fator_cotacao: 1 = cotação unitária; 1000 = cotação por lote de mil; preco_exercicio_pontos: pontos (1 ponto = 1/100 US$ nas opções referenciadas em dólar); dismes: número de sequência |
| Dados pessoais | nenhum |
| Eras | 1986-01: Início da série. Na amostra de 1986 o símbolo da moeda é CZ$ ou CR$ (campo moeda de referência); em 2012 e 2026 é R$; 1995-05: O campo CODISI passa a trazer o ISIN, segundo o layout (antes, código interno do papel, de 8 a 10 caracteres na amostra de 1986); 2020-10: Revisão 2.0 do documento de layout (05/10/2020) atualiza a tabela de especificações (ESPECI); 2026-10: Registros isolados passam a vir em UTF-8 dentro do arquivo Latin-1 (observado em 2026-10-22, nome resumido FROTA OCEÂNI); o conversor os lê como UTF-8 |
| Revisado em | 2026-11-09 |
| Versão do fetcher | 0.4.1 |
Origem e coleta¶
- O fetcher baixa
COTAHIST_A<ano>.zipdo endereço de distribuição oficial da série histórica, um por ano, de 1986 até o ano corrente. O arquivo de 1985 não existe na fonte. - No bruto, cada ano é
cotacaohistorica_<AAAA>@<AAAAMMDD>.zip. O sufixo é a data do cabeçalhoLast-Modifieddo arquivo na fonte (ou a data da coleta, quando ela não vem); cada versão nova do arquivo fica como um arquivo distinto. - Conferido em 2026-11-09 pela listagem do bruto: um arquivo por ano de 1986 a 2025 e, em 2026, seis versões (de 2026-10-27 a 2026-11-04). Sem lacunas de anos.
- O ZIP tem um TXT (nos arquivos antigos, um membro único sem extensão). O conversor lê só os registros
01; os registros00(cabeçalho) e99(rodapé, com o total de registros) são descartados.
Conteúdo¶
- Unidade: um papel-mercado em um pregão. Para o mesmo código de negociação pode haver linhas em mercados diferentes (por exemplo, à vista e fracionário), identificados por
tipo_mercado_idebdi_id. - Amostras convertidas em 2026-11-09 (não são a série completa): 1986 com 177.981 linhas (248 pregões), 2012 com 330.633 (246 pregões) e 2026 com 3.398.579 (210 pregões, de 2026-01-02 a 2026-11-04, versão de 04/11).
- A data de cada linha pertence ao ano do arquivo nas três amostras (nenhuma linha fora do ano).
- Eras: veja o cabeçalho. A mudança da moeda nos primeiros anos aparece no campo
simbolo_moeda; a B3 entrega o valor na moeda da época, sem conversão.
Variáveis¶
Descrições e códigos vêm do documento oficial "Layout do arquivo - Cotações Históricas", revisão de 05/10/2020 (SeriesHistoricas_Layout.pdf). A coluna "Na fonte" traz o nome do campo no layout. Colunas decimais têm vírgula implícita no arquivo e viram decimal exato no lake. A coluna ano é a partição.
| Coluna no lake | Na fonte | Tipo | Descrição | Unidade / códigos | Período |
|---|---|---|---|---|---|
ano |
ano do nome do arquivo | inteiro (partição) | Ano do arquivo COTAHIST_A<ano> |
ano de 4 dígitos | todo |
tipreg |
TIPREG |
inteiro | Tipo de registro; fixo "01" no layout | sempre 1 | todo |
data |
DATA (data do pregão) |
data | Data do pregão (AAAAMMDD na fonte) |
— | todo |
bdi_id |
CODBDI |
texto | Código BDI, "utilizado para classificar os papéis na emissão do Boletim Diário de Informações" | 2 caracteres, como 02; tabela CODBDI do layout (veja cuidados de uso) |
todo |
simbolo |
CODNEG |
texto | Código de negociação do papel | até 12 caracteres | todo |
tipo_mercado_id |
TPMERC |
inteiro | Código do mercado em que o papel está cadastrado | 10 vista; 12 exercício de opções de compra; 13 exercício de opções de venda; 17 leilão; 20 fracionário; 30 termo; 50 futuro com retenção de ganho; 60 futuro com movimentação contínua; 70 opções de compra; 80 opções de venda (tabela TPMERC do layout) | todo |
nome_resumido |
NOMRES |
texto | Nome resumido da empresa emissora do papel | até 12 caracteres (truncado pela fonte) | todo |
especificacao_id |
ESPECI |
texto | Especificação do papel | tabela ESPECI do layout, por exemplo ON, PN, UNT, CI, BDR; os dados trazem também sufixos de nível de governança (ON NM, PN N1) |
todo |
prazo |
PRAZOT |
texto | Prazo em dias do mercado a termo | 3 caracteres, como 030; vazio fora do termo e das opções |
todo |
simbolo_moeda |
MODREF |
texto | Moeda de referência: moeda usada na data do pregão | CZ$, CR$ (1986), R$ |
todo |
preco_abertura |
PREABE |
decimal(13,2) | Preço de abertura do papel-mercado no pregão | moeda da época | todo |
preco_maximo |
PREMAX |
decimal(13,2) | Preço máximo do papel-mercado no pregão | moeda da época | todo |
preco_minimo |
PREMIN |
decimal(13,2) | Preço mínimo do papel-mercado no pregão | moeda da época | todo |
preco_medio |
PREMED |
decimal(13,2) | Preço médio do papel-mercado no pregão | moeda da época | todo |
preco_ultimo_negocio |
PREULT |
decimal(13,2) | Preço do último negócio do papel-mercado no pregão | moeda da época | todo |
preco_melhor_oferta_compra |
PREOFC |
decimal(13,2) | Preço da melhor oferta de compra do papel-mercado | moeda da época; 0,00 quando não há | todo |
preco_melhor_oferta_venda |
PREOFV |
decimal(13,2) | Preço da melhor oferta de venda do papel-mercado | moeda da época; 0,00 quando não há | todo |
quantidade_negocios |
TOTNEG |
inteiro | Número de negócios efetuados com o papel-mercado no pregão | negócios | todo |
quantidade_titulos_negociados |
QUATOT |
inteiro | Quantidade total de títulos negociados neste papel-mercado | títulos | todo |
volume_negociado |
VOLTOT |
decimal(18,2) | Volume total de títulos negociados neste papel-mercado | moeda da época | todo |
preco_exercicio |
PREEXE |
decimal(13,2) | Preço de exercício para o mercado de opções ou valor do contrato para o mercado de termo secundário | moeda da época | todo |
indice_correcao_id |
INDOPC |
inteiro | Indicador de correção de preços de exercícios ou valores de contrato para opções ou termo secundário | 1 US$ (correção pela taxa do dólar); 2 TJLP; 8 IGP-M (opções protegidas); 9 URV; nas amostras só aparece 0, que a tabela não define | todo |
data_vencimento |
DATVEN |
data | Data do vencimento para os mercados de opções ou termo secundário | data; as amostras trazem 9999-12-31 nas linhas sem vencimento (observação, a fonte não define) | todo |
fator_cotacao |
FATCOT |
inteiro | Fator de cotação do papel | 1 = cotação unitária; 1000 = cotação por lote de mil ações; as amostras de 2026 trazem também 100, 10000 e 1000000, que o layout não descreve | todo |
preco_exercicio_pontos |
PTOEXE |
decimal(13,6) | Preço de exercício em pontos para opções referenciadas em dólar, ou valor de contrato em pontos para termo secundário | pontos; 1 ponto = 1/100 US$ | todo |
codisi |
CODISI |
texto | Código do papel no sistema ISIN ou código interno do papel | ISIN (12 caracteres) a partir de 15-05-1995; antes, código interno | todo |
dismes |
DISMES |
inteiro | Número de distribuição do papel: sequência do papel correspondente ao estado de direito vigente | número de sequência | todo |
No lake¶
- Dataset
b3/cotacaohistorica, particionado porano; um Parquet por versão do arquivo. - A partição
anovem do nome do arquivo (..._A<ano>ou o ano no nome), não da colunadata. - Só os registros
01entram. Campos de texto são aparados e têm espaços repetidos reduzidos a um; campos numéricos em branco viram nulo; qualquer valor que não caiba no tipo do layout faz a conversão falhar, em vez de virar nulo. - Datas viram
date; campos com vírgula implícita viram decimal exato (precisão igual ao tamanho do campo, escala igual às casas decimais do layout), nunca ponto flutuante. - Códigos (
bdi_id,simbolo,codisi) ficam como texto, preservando zeros à esquerda. - Texto em branco vira texto vazio (
""), não nulo; é o caso deprazofora do termo (132.566 de 177.981 linhas em 1986) e denome_resumidoem 14 linhas de 2026. - Os registros vêm em Latin-1; o conversor trata como UTF-8 as poucas linhas que, lidas em Latin-1, passariam de 245 caracteres e decodificam em UTF-8 com exatamente 245.
- O esquema de referência (
cotacaohistorica.schema.json) tem 26 colunas, gerado de uma conversão das amostras de 1986, 2012 e 2026.
Cuidados de uso¶
- Sem ajuste de proventos. A fonte avisa que as cotações são fornecidas na moeda e forma de cotação da época, sem ajuste para inflação nem para proventos (dividendos, bonificações, subscrição). Retornos calculados direto do preço de fechamento erram nos dias de desdobramentos, grupamentos e proventos.
- Moeda da época. Em 1986 as amostras trazem
CZ$eCR$; compare preços entre épocas só depois de converter moedas. - Cotação por lote. Quando
fator_cotacaoé 1000, o preço é por lote de mil; divida o preço pelo fator para obter o preço unitário. Em 2026 há linhas com fatores 100, 10000 e 1000000 que o layout não descreve (evidência: amostra de 2026, 2026-11-09). - Uma ação, várias linhas. O mesmo papel pode aparecer em mercados diferentes. Para o preço de um papel no mercado à vista em lote padrão, filtre
tipo_mercado_id = 10ebdi_id = '02'; no PETR4 de 2026 isso dá uma linha por pregão (210 linhas em 210 pregões, amostra de 2026-11-09). - Códigos fora das tabelas do layout. Nas amostras há códigos de BDI que a tabela da revisão de 05/10/2020 não lista:
30(5 linhas em 2012) e34,36,35,93,13e92em 2026; e o tipo de mercado21(2.106 linhas em 2026). Não atribuímos significado a eles; a fonte não os descreve nesse documento. - Especificação além da tabela. As amostras trazem especificações como
ON NM,PN N1,UNT N2eDRNque não constam da tabela anexa; a tabela do layout cobre só parte dos valores (em 2026, 2.930.502 de 3.398.579 linhas têm valor fora da tabela distribuída com o fetcher). - Tabelas auxiliares do fetcher. O fetcher distribui cópias das tabelas do layout (
codbdi,especi,indopc,tpmerc) emread_dimension. A cópia deespeci(100 valores) difere da revisão de 05/10/2020: não tem, por exemplo,CI ATZ,FIDCnemON ATZ, e trazPNF,PNGePNH, que a revisão não lista; a descrição de alguns valores... Pestá truncada. Não use essas cópias como referência única. - Vencimento 9999-12-31. Linhas sem vencimento trazem essa data; descarte-a antes de calcular prazos.
- Chave. Não há chave única simples: na amostra de 1986, combinar data, símbolo, mercado, BDI, especificação, prazo, vencimento, preço de exercício e ISIN deixa uma duplicata; em 2012 e 2026 essa combinação é única.
- Dado suspeito na fonte. Na amostra de 1986 há uma linha com preço máximo menor que o mínimo, e em 2026, 51 linhas com preço do último negócio igual a zero. Nenhuma foi corrigida.
- Termos de uso. Veja os termos citados na licença antes de redistribuir.
Exemplos¶
Fechamento de PETR4 no mercado à vista em lote padrão, preço unitário (divide pelo fator de cotação):
import polars as pl
cot = pl.scan_parquet("lake/b3/cotacaohistorica/**/*.parquet", hive_partitioning=True)
petr4 = (
cot.filter(
(pl.col("simbolo") == "PETR4")
& (pl.col("tipo_mercado_id") == 10)
& (pl.col("bdi_id") == "02")
& (pl.col("ano") == 2026)
)
.select(
"data",
(pl.col("preco_ultimo_negocio") / pl.col("fator_cotacao")).alias("fechamento"),
)
.sort("data")
.collect()
)
Referências¶
- Página da série histórica: https://www.b3.com.br/pt_br/market-data-e-indices/servicos-de-dados/market-data/historico/mercado-a-vista/cotacoes-historicas/
- Layout do arquivo de cotações históricas (revisão de 05/10/2020): https://www.b3.com.br/data/files/33/67/B9/50/D84057102C784E47AC094EA8/SeriesHistoricas_Layout.pdf
- Termos e Condições de Uso da B3: https://www.b3.com.br/pt_br/termos-de-uso-e-protecao-de-dados/termos-de-uso/