B3 - Bolsa de Valores do Brasil

Este módulo contém funções para acessar dados de mercado da B3 (Brasil, Bolsa, Balcão).

`fetch_intraday_derivatives(contract_code)`

Busca cotações intraday brutas de derivativos da B3.

Faz a chamada ao endpoint DerivativeQuotation e devolve um DataFrame padronizado, sem enriquecimento de regra de negócio.

As colunas de cotação e limites são retornadas com prefixo preco_. A fonte intraday da B3 opera com atraso aproximado de 15 minutos. Para contratos cotados por taxa, a conversão para taxa_ e cálculos derivados devem ser feitos no módulo consumidor.

Parameters:

Name	Type	Description	Default
`contract_code`	`str`	Código base do derivativo na B3.	required

Returns:

Type	Description
`DataFrame`	DataFrame Polars com o payload normalizado da API.

Output Columns

codigo_negociacao (String): código de negociação na B3.
descricao (String): descrição do instrumento.
codigo_ativo (String): código do ativo base.
codigo_mercado (String): código do mercado (ex.: FUT, OPTEXER, SOPT, SPOT).
data_vencimento (Date): data de vencimento do contrato.
preco_ajuste_anterior (Float64): preço de ajuste do dia anterior.
preco_limite_minimo (Float64): limite mínimo de variação.
preco_limite_maximo (Float64): limite máximo de variação.
preco_abertura (Float64): preço de abertura.
preco_minimo (Float64): preço mínimo negociado.
preco_maximo (Float64): preço máximo negociado.
preco_medio (Float64): preço médio negociado.
preco_ultimo (Float64): último preço negociado.
preco_exercicio (Float64): preço de exercício (opções).
contratos_abertos (Int64): contratos em aberto.
volume_financeiro (Float64): volume financeiro bruto.
numero_negocios (Int64): número de negócios.
volume_negociado (Int64): quantidade de contratos negociados.
preco_oferta_compra (Float64): melhor oferta de compra (opcional).
preco_oferta_venda (Float64): melhor oferta de venda (opcional).
tipo_lado (String): tipo de lado (opcional).
atualizado_as (Datetime): horário aproximado a que o dado se refere (horário da consulta menos 15 min de atraso da fonte).

Source code in pyield/b3/intraday_derivatives.py

def fetch_intraday_derivatives(contract_code: str) -> pl.DataFrame:
    """Busca cotações intraday brutas de derivativos da B3.

    Faz a chamada ao endpoint ``DerivativeQuotation`` e devolve um DataFrame
    padronizado, sem enriquecimento de regra de negócio.

    As colunas de cotação e limites são retornadas com prefixo ``preco_``.
    A fonte intraday da B3 opera com atraso aproximado de 15 minutos.
    Para contratos cotados por taxa, a conversão para ``taxa_`` e cálculos
    derivados devem ser feitos no módulo consumidor.

    Args:
        contract_code: Código base do derivativo na B3.

    Returns:
        DataFrame Polars com o payload normalizado da API.

    Output Columns:
        * codigo_negociacao (String): código de negociação na B3.
        * descricao (String): descrição do instrumento.
        * codigo_ativo (String): código do ativo base.
        * codigo_mercado (String): código do mercado (ex.: FUT, OPTEXER, SOPT, SPOT).
        * data_vencimento (Date): data de vencimento do contrato.
        * preco_ajuste_anterior (Float64): preço de ajuste do dia anterior.
        * preco_limite_minimo (Float64): limite mínimo de variação.
        * preco_limite_maximo (Float64): limite máximo de variação.
        * preco_abertura (Float64): preço de abertura.
        * preco_minimo (Float64): preço mínimo negociado.
        * preco_maximo (Float64): preço máximo negociado.
        * preco_medio (Float64): preço médio negociado.
        * preco_ultimo (Float64): último preço negociado.
        * preco_exercicio (Float64): preço de exercício (opções).
        * contratos_abertos (Int64): contratos em aberto.
        * volume_financeiro (Float64): volume financeiro bruto.
        * numero_negocios (Int64): número de negócios.
        * volume_negociado (Int64): quantidade de contratos negociados.
        * preco_oferta_compra (Float64): melhor oferta de compra (opcional).
        * preco_oferta_venda (Float64): melhor oferta de venda (opcional).
        * tipo_lado (String): tipo de lado (opcional).
        * atualizado_as (Datetime): horário aproximado a que o dado se
          refere (horário da consulta menos 15 min de atraso da fonte).
    """
    if not intraday_disponivel():
        return pl.DataFrame()

    dados_json = _buscar_json_intraday(contract_code)
    if not dados_json:
        return pl.DataFrame()

    return (
        _converter_json_intraday(dados_json)
        .pipe(_processar_colunas_intraday)
        .with_columns(
            atualizado_as=clock.now() - dt.timedelta(minutes=15),
        )
        .sort("codigo_negociacao")
    )

`fetch_price_report(date, contract_code, full_report=False)`

Busca e processa o price report da B3 no site oficial.

Faz o download do ZIP com XML, extrai os dados do contrato e devolve um DataFrame Polars com os dados brutos do XML e colunas no padrão original da B3 (nomes em inglês das tags XML).

O DataFrame retornado não contém colunas calculadas (dias_uteis, dias_corridos, dv01, taxa_forward) nem normalização semântica por classe de ativo. O enriquecimento é responsabilidade do módulo consumidor (ex.: futures.historical).

Nota

O dataset cacheado pr (arquivo b3_pr.parquet) pode conter um subconjunto de colunas focado em futuros. Esta função, porém, opera no schema bruto do XML da B3 para a data/relatório consultados.

Parameters:

Name	Type	Description	Default
`date`	`DateLike`	Data de negociação no formato 'DD-MM-YYYY', 'DD/MM/YYYY', 'YYYY-MM-DD' ou objeto datetime.date.	required
`contract_code`	`str \| list[str]`	Código B3 único ou lista de códigos (ex.: 'DI1', ['DI1', 'DAP']). Os 3 primeiros caracteres são usados no XML.	required
`full_report`	`bool`	Se False (padrão), usa o simplified price report (SPR), arquivo leve (~2 KB) com apenas preços de ajuste. Se True, usa o price report completo (PR, ~2 MB) com todos os dados de negociação.	`False`

Returns:

Type	Description
`DataFrame`	pl.DataFrame: DataFrame com colunas tipadas no padrão original do XML,
`DataFrame`	ordenado por ticker (`TckrSymb`). Inclui todos os registros do XML (sem filtro de
`DataFrame`	vencimento). Retorna DataFrame vazio para data inválida ou resposta
`DataFrame`	vazia.

Output Columns

TradDt (Date): data de negociação.
TckrSymb (String): código de negociação na B3.
Id (String): identificador do instrumento.
Prtry (String): tipo do identificador proprietário.
MktIdrCd (String): código do mercado.
DaysToSttlm (Int64): dias para liquidação.
TradQty (Int64): número de negócios.
MktDataStrmId (String): identificador do fluxo de dados.
NtlFinVol (Float64): volume financeiro nacional bruto.
IntlFinVol (Float64): volume financeiro internacional.
OpnIntrst (Int64): contratos em aberto.
FinInstrmQty (Int64): quantidade negociada de instrumentos financeiros. * BestBidPric (Float64): ultima melhor oferta de compra no snapshot diario; pode ser nulo. * BestAskPric (Float64): ultima melhor oferta de venda no snapshot diario; pode ser nulo.
FrstPric (Float64): preço de abertura.
MinPric (Float64): preço mínimo negociado.
MaxPric (Float64): preço máximo negociado.
TradAvrgPric (Float64): preço médio negociado.
LastPric (Float64): preço de fechamento.
RglrTxsQty (Int64): número de negócios regulares.
NonRglrTxsQty (Int64): número de negócios não regulares.
RglrTraddCtrcts (Int64): contratos regulares negociados.
NonRglrTraddCtrcts (Int64): contratos não regulares negociados.
NtlRglrVol (Float64): volume financeiro regular nacional.
NtlNonRglrVol (Float64): volume não regular nacional.
IntlRglrVol (Float64): volume regular internacional.
IntlNonRglrVol (Float64): volume não regular internacional.
AdjstdQt (Float64): preço/cotação de ajuste.
AdjstdQtTax (Float64): taxa de ajuste.
AdjstdQtStin (String): indicador de cotação ajustada.
PrvsAdjstdQt (Float64): preço/cotação de ajuste do dia anterior.
PrvsAdjstdQtTax (Float64): taxa de ajuste do dia anterior.
PrvsAdjstdQtStin (String): indicador de ajuste anterior.
OscnPctg (Float64): percentual de oscilação.
VartnPts (Float64): variação em pontos.
EqvtVal (Float64): valor equivalente.
AdjstdValCtrct (Float64): valor do contrato ajustado.
MaxTradLmt (Float64): limite máximo de variação.
MinTradLmt (Float64): limite mínimo de variação.

Raises:

Type	Description
`HTTPError`	Se a requisição HTTP ao endpoint falhar.
`BadZipFile`	Se o ZIP estiver corrompido após re-download.
`XMLSyntaxError`	Se o XML recebido estiver malformado.

Examples:

>>> import pyield as yd
>>> df = yd.b3.fetch_price_report("26-04-2024", "DI1")

>>> # Múltiplos contratos de uma vez
>>> df = yd.b3.fetch_price_report("26-04-2024", ["DI1", "DAP"])

>>> # Feriado ou fim de semana (retorna DataFrame vazio)
>>> df = yd.b3.fetch_price_report("25-12-2023", "DI1")  # Véspera de Natal
>>> df.is_empty()
True

Source code in pyield/b3/price_report.py

def fetch_price_report(
    date: DateLike,
    contract_code: str | list[str],
    full_report: bool = False,
) -> pl.DataFrame:
    """Busca e processa o price report da B3 no site oficial.

    Faz o download do ZIP com XML, extrai os dados do contrato e devolve um
    DataFrame Polars com os dados brutos do XML e colunas no padrão
    original da B3 (nomes em inglês das tags XML).

    O DataFrame retornado **não** contém colunas calculadas
    (dias_uteis, dias_corridos, dv01, taxa_forward)
    nem normalização semântica por classe de ativo. O enriquecimento é responsabilidade do
    módulo consumidor (ex.: ``futures.historical``).

    Nota:
        O dataset cacheado ``pr`` (arquivo ``b3_pr.parquet``) pode conter um
        subconjunto de colunas focado em futuros. Esta função, porém, opera no
        schema bruto do XML da B3 para a data/relatório consultados.

    Args:
        date: Data de negociação no formato 'DD-MM-YYYY', 'DD/MM/YYYY',
            'YYYY-MM-DD' ou objeto datetime.date.
        contract_code: Código B3 único ou lista de códigos (ex.: 'DI1',
            ['DI1', 'DAP']). Os 3 primeiros caracteres são usados no XML.
        full_report: Se False (padrão), usa o simplified price report (SPR),
            arquivo leve (~2 KB) com apenas preços de ajuste. Se True, usa o
            price report completo (PR, ~2 MB) com todos os dados de negociação.

    Returns:
        pl.DataFrame: DataFrame com colunas tipadas no padrão original do XML,
        ordenado por ticker (`TckrSymb`). Inclui todos os registros do XML (sem filtro de
        vencimento). Retorna DataFrame vazio para data inválida ou resposta
        vazia.

    Output Columns:
        * TradDt (Date): data de negociação.
        * TckrSymb (String): código de negociação na B3.
        * Id (String): identificador do instrumento.
        * Prtry (String): tipo do identificador proprietário.
        * MktIdrCd (String): código do mercado.
        * DaysToSttlm (Int64): dias para liquidação.
        * TradQty (Int64): número de negócios.
        * MktDataStrmId (String): identificador do fluxo de dados.
        * NtlFinVol (Float64): volume financeiro nacional bruto.
        * IntlFinVol (Float64): volume financeiro internacional.
        * OpnIntrst (Int64): contratos em aberto.
        * FinInstrmQty (Int64): quantidade negociada de instrumentos financeiros.
                * BestBidPric (Float64): ultima melhor oferta de compra no snapshot
                    diario; pode ser nulo.
                * BestAskPric (Float64): ultima melhor oferta de venda no snapshot
                    diario; pode ser nulo.
        * FrstPric (Float64): preço de abertura.
        * MinPric (Float64): preço mínimo negociado.
        * MaxPric (Float64): preço máximo negociado.
        * TradAvrgPric (Float64): preço médio negociado.
        * LastPric (Float64): preço de fechamento.
        * RglrTxsQty (Int64): número de negócios regulares.
        * NonRglrTxsQty (Int64): número de negócios não regulares.
        * RglrTraddCtrcts (Int64): contratos regulares negociados.
        * NonRglrTraddCtrcts (Int64): contratos não regulares negociados.
        * NtlRglrVol (Float64): volume financeiro regular nacional.
        * NtlNonRglrVol (Float64): volume não regular nacional.
        * IntlRglrVol (Float64): volume regular internacional.
        * IntlNonRglrVol (Float64): volume não regular internacional.
        * AdjstdQt (Float64): preço/cotação de ajuste.
        * AdjstdQtTax (Float64): taxa de ajuste.
        * AdjstdQtStin (String): indicador de cotação ajustada.
        * PrvsAdjstdQt (Float64): preço/cotação de ajuste do dia anterior.
        * PrvsAdjstdQtTax (Float64): taxa de ajuste do dia anterior.
        * PrvsAdjstdQtStin (String): indicador de ajuste anterior.
        * OscnPctg (Float64): percentual de oscilação.
        * VartnPts (Float64): variação em pontos.
        * EqvtVal (Float64): valor equivalente.
        * AdjstdValCtrct (Float64): valor do contrato ajustado.
        * MaxTradLmt (Float64): limite máximo de variação.
        * MinTradLmt (Float64): limite mínimo de variação.

    Raises:
        requests.HTTPError: Se a requisição HTTP ao endpoint falhar.
        zipfile.BadZipFile: Se o ZIP estiver corrompido após re-download.
        etree.XMLSyntaxError: Se o XML recebido estiver malformado.

    Examples:
        >>> import pyield as yd
        >>> df = yd.b3.fetch_price_report("26-04-2024", "DI1")

        >>> # Múltiplos contratos de uma vez
        >>> df = yd.b3.fetch_price_report("26-04-2024", ["DI1", "DAP"])

        >>> # Feriado ou fim de semana (retorna DataFrame vazio)
        >>> df = yd.b3.fetch_price_report("25-12-2023", "DI1")  # Véspera de Natal
        >>> df.is_empty()
        True
    """
    contratos = normalizar_codigos_contrato(contract_code)
    if any_is_empty(date) or not contratos:
        return pl.DataFrame()

    date = cv.converter_datas(date)
    # Validação centralizada (evita chamadas desnecessárias às APIs B3)
    if not data_negociacao_valida(date):
        return pl.DataFrame()

    xml_bytes = _obter_xml_price_report(date, full_report)
    dataframes = []
    for contrato in contratos:
        df = _processar_xml_extraido(xml_bytes, contrato)
        if not df.is_empty():
            dataframes.append(df)
    if not dataframes:
        return pl.DataFrame()
    return pl.concat(dataframes, how="diagonal").sort("TckrSymb")

`read_price_report(xml_bytes, contract_code)`

Lê e processa o price report da B3 a partir do conteúdo XML bruto.

Mesma saída de :func:fetch_price_report, mas recebe o XML já descomprimido em vez de baixar da rede.

Parameters:

Name	Type	Description	Default
`xml_bytes`	`bytes`	Conteúdo do XML em bytes (já descomprimido).	required
`contract_code`	`str \| list[str]`	Código B3 único ou lista de códigos (ex.: 'DI1', ['DI1', 'DAP']).	required

Returns:

Type	Description
`DataFrame`	pl.DataFrame: DataFrame com as mesmas colunas documentadas em
`DataFrame`	func:`fetch_price_report`.

Source code in pyield/b3/price_report.py

def read_price_report(
    xml_bytes: bytes,
    contract_code: str | list[str],
) -> pl.DataFrame:
    """Lê e processa o price report da B3 a partir do conteúdo XML bruto.

    Mesma saída de :func:`fetch_price_report`, mas recebe o XML já
    descomprimido em vez de baixar da rede.

    Args:
        xml_bytes: Conteúdo do XML em bytes (já descomprimido).
        contract_code: Código B3 único ou lista de códigos (ex.: 'DI1',
            ['DI1', 'DAP']).

    Returns:
        pl.DataFrame: DataFrame com as mesmas colunas documentadas em
        :func:`fetch_price_report`.
    """
    contratos = normalizar_codigos_contrato(contract_code)
    if any_is_empty(xml_bytes) or not contratos:
        return pl.DataFrame()

    dataframes = []
    for contrato in contratos:
        df = _processar_xml_extraido(xml_bytes, contrato)
        if not df.is_empty():
            dataframes.append(df)
    if not dataframes:
        return pl.DataFrame()
    return pl.concat(dataframes, how="diagonal").sort("TckrSymb")