Tesouro Data

`auction(auction_date)`

Fetches and processes Brazilian Treasury auction data for a given date.

This function queries the Tesouro Nacional API to retrieve auction results for a specific date. It then processes the JSON response using the Polars library to create a well-structured and typed DataFrame.

Exemplo de resposta da API de leilões do Tesouro: https://apiapex.tesouro.gov.br/aria/v1/api-leiloes-pub/custom/resultados?dataleilao=30/09/2025

{
"registros": [
    {...},
    {
    "quantidade_bcb": 0,
    "liquidacao_segunda_volta": "2025-10-01T00:00:00.000Z",
    "oferta_segunda_volta": 37499,
    "data_leilao": "30/09/2025",
    "oferta": 150000,
    "titulo": "LFT",
    "liquidacao": "01/10/2025",
    "financeiro_aceito_segunda_volta": 0,
    "quantidade_aceita": 150000,
    "prazo": 1067,
    "vencimento": "01/09/2028",
    "benchmark": "LFT 3 anos",
    "pu_medio": 17434.81182753125,
    "taxa_media": 0.0669,
    "financeiro_aceito": 2615194916.22,
    "pu_minimo": 17434.632775,
    "numero_edital": 230,
    "taxa_maxima": 0.0669,
    "tipo_leilao": "Venda",
    "financeiro_bcb": 0,
    "quantidade_aceita_segunda_volta": 0
    },
    {...},
],
"status": "ok"
}

Parameters:

Name	Type	Description	Default
`auction_date`	`DateScalar`	The date of the auction in the format accepted by PYield DateScalar (e.g., "DD-MM-YYYY", datetime.date, etc.).	required

Returns:

Type	Description
`DataFrame`	Um DataFrame do Polars contendo os dados processados do leilão. As colunas são:
`DataFrame`	data_1v: Data de realização do leilão (1ª volta).
`DataFrame`	data_liquidacao_1v: Data de liquidação financeira da 1ª volta.
`DataFrame`	data_liquidacao_2v: Data de liquidação financeira da 2ª volta (se houver).
`DataFrame`	numero_edital: Número do edital que rege o leilão.
`DataFrame`	tipo_leilao: Tipo da operação (ex: "Venda", "Compra").
`DataFrame`	titulo: Código do título público leiloado (ex: "NTN-B", "LFT").
`DataFrame`	benchmark: Descrição de referência do título (ex: "NTN-B 3 anos").
`DataFrame`	data_vencimento: Data de vencimento do título.
`DataFrame`	dias_uteis: Número de dias úteis entre a liquidação (1v) e o vencimento.
`DataFrame`	dias_corridos: Prazo em dias corridos do título, conforme informado pela API.
`DataFrame`	duration: A Duração de Macaulay do título em anos, calculada entre a liquidação da 1ª volta e o vencimento do título.
`DataFrame`	prazo_medio: A maturidade média do título em anos, conforme metodologia do Tesouro, calculada entre a liquidação da 1ª volta e o vencimento do título.
`DataFrame`	quantidade_ofertada_1v: Quantidade de títulos ofertados na 1ª volta.
`DataFrame`	quantidade_ofertada_2v: Quantidade de títulos ofertados na 2ª volta.
`DataFrame`	quantidade_aceita_1v: Quantidade de títulos com propostas aceitas na 1ª volta.
`DataFrame`	quantidade_aceita_2v: Quantidade de títulos aceitos na 2ª volta.
`DataFrame`	quantidade_aceita_total: Soma das quantidades aceitas nas duas voltas.
`DataFrame`	financeiro_ofertado_1v: Financeiro ofertado total na 1ª volta (em BRL).
`DataFrame`	financeiro_ofertado_2v: Financeiro ofertado total na 2ª volta (em BRL).
`DataFrame`	financeiro_ofertado_total: Financeiro total ofertado nas duas voltas (em BRL).
`DataFrame`	financeiro_aceito_1v: Financeiro aceito total na 1ª volta (em BRL).
`DataFrame`	financeiro_aceito_2v: Financeiro aceito total na 2ª volta (em BRL).
`DataFrame`	financeiro_aceito_total: Soma do financeiro aceito nas duas voltas (em BRL).
`DataFrame`	quantidade_bcb: Quantidade de títulos adquirida pelo Banco Central.
`DataFrame`	financeiro_bcb: Financeiro adquirido pelo Banco Central.
`DataFrame`	colocacao_1v: Taxa de colocação da 1ª volta (quantidade aceita / ofertada).
`DataFrame`	colocacao_2v: Taxa de colocação da 2ª volta (quantidade aceita / ofertada).
`DataFrame`	colocacao_total: Taxa de colocação total (quantidade aceita / ofertada).
`DataFrame`	dv01_1v: DV01 da 1ª volta em BRL.
`DataFrame`	dv01_2v: DV01 da 2ª volta em BRL.
`DataFrame`	dv01_total: DV01 total do leilão em BRL.
`DataFrame`	dv01_1v_usd: DV01 da 1ª volta em USD usando a PTAX do dia.
`DataFrame`	dv01_2v_usd: DV01 da 2ª volta em USD usando a PTAX do dia.
`DataFrame`	dv01_total_usd: DV01 total das duas voltas em USD usando a PTAX do dia.
`DataFrame`	pu_minimo: Preço Unitário mínimo aceito no leilão.
`DataFrame`	pu_medio: Preço Unitário médio ponderado das propostas aceitas.
`DataFrame`	tipo_pu_medio: Indica se o PU médio é "original" (fornecido pela API) ou "calculado" (recalculado pela função).
`DataFrame`	taxa_media: Taxa de juros média das propostas aceitas (em formato decimal).
`DataFrame`	taxa_maxima: Taxa de juros máxima aceita no leilão (taxa de corte, em formato decimal).

Retorna um DataFrame do Pandas vazio se ocorrer um erro na requisição, no processamento, ou se não houver dados para a data especificada.

Source code in pyield/tn/auctions.py

def auction(auction_date: DateScalar) -> pl.DataFrame:
    """
    Fetches and processes Brazilian Treasury auction data for a given date.

    This function queries the Tesouro Nacional API to retrieve auction results
    for a specific date. It then processes the JSON response using the Polars
    library to create a well-structured and typed DataFrame.

    Exemplo de resposta da API de leilões do Tesouro:
    https://apiapex.tesouro.gov.br/aria/v1/api-leiloes-pub/custom/resultados?dataleilao=30/09/2025

        {
        "registros": [
            {...},
            {
            "quantidade_bcb": 0,
            "liquidacao_segunda_volta": "2025-10-01T00:00:00.000Z",
            "oferta_segunda_volta": 37499,
            "data_leilao": "30/09/2025",
            "oferta": 150000,
            "titulo": "LFT",
            "liquidacao": "01/10/2025",
            "financeiro_aceito_segunda_volta": 0,
            "quantidade_aceita": 150000,
            "prazo": 1067,
            "vencimento": "01/09/2028",
            "benchmark": "LFT 3 anos",
            "pu_medio": 17434.81182753125,
            "taxa_media": 0.0669,
            "financeiro_aceito": 2615194916.22,
            "pu_minimo": 17434.632775,
            "numero_edital": 230,
            "taxa_maxima": 0.0669,
            "tipo_leilao": "Venda",
            "financeiro_bcb": 0,
            "quantidade_aceita_segunda_volta": 0
            },
            {...},
        ],
        "status": "ok"
        }

    Args:
        auction_date: The date of the auction in the format accepted by PYield
            DateScalar (e.g., "DD-MM-YYYY", datetime.date, etc.).

    Returns:
        Um DataFrame do Polars contendo os dados processados do leilão. As colunas são:
        - data_1v: Data de realização do leilão (1ª volta).
        - data_liquidacao_1v: Data de liquidação financeira da 1ª volta.
        - data_liquidacao_2v: Data de liquidação financeira da 2ª volta (se houver).
        - numero_edital: Número do edital que rege o leilão.
        - tipo_leilao: Tipo da operação (ex: "Venda", "Compra").
        - titulo: Código do título público leiloado (ex: "NTN-B", "LFT").
        - benchmark: Descrição de referência do título (ex: "NTN-B 3 anos").
        - data_vencimento: Data de vencimento do título.
        - dias_uteis: Número de dias úteis entre a liquidação (1v) e o vencimento.
        - dias_corridos: Prazo em dias corridos do título, conforme informado pela API.
        - duration: A Duração de Macaulay do título em anos, calculada entre a
            liquidação da 1ª volta e o vencimento do título.
        - prazo_medio: A maturidade média do título em anos, conforme metodologia do
            Tesouro, calculada entre a liquidação da 1ª volta e o vencimento do título.
        - quantidade_ofertada_1v: Quantidade de títulos ofertados na 1ª volta.
        - quantidade_ofertada_2v: Quantidade de títulos ofertados na 2ª volta.
        - quantidade_aceita_1v: Quantidade de títulos com propostas aceitas na 1ª volta.
        - quantidade_aceita_2v: Quantidade de títulos aceitos na 2ª volta.
        - quantidade_aceita_total: Soma das quantidades aceitas nas duas voltas.
        - financeiro_ofertado_1v: Financeiro ofertado total na 1ª volta (em BRL).
        - financeiro_ofertado_2v: Financeiro ofertado total na 2ª volta (em BRL).
        - financeiro_ofertado_total: Financeiro total ofertado nas duas voltas (em BRL).
        - financeiro_aceito_1v: Financeiro aceito total na 1ª volta (em BRL).
        - financeiro_aceito_2v: Financeiro aceito total na 2ª volta (em BRL).
        - financeiro_aceito_total: Soma do financeiro aceito nas duas voltas (em BRL).
        - quantidade_bcb: Quantidade de títulos adquirida pelo Banco Central.
        - financeiro_bcb: Financeiro adquirido pelo Banco Central.
        - colocacao_1v: Taxa de colocação da 1ª volta (quantidade aceita / ofertada).
        - colocacao_2v: Taxa de colocação da 2ª volta (quantidade aceita / ofertada).
        - colocacao_total: Taxa de colocação total (quantidade aceita / ofertada).
        - dv01_1v: DV01 da 1ª volta em BRL.
        - dv01_2v: DV01 da 2ª volta em BRL.
        - dv01_total: DV01 total do leilão em BRL.
        - dv01_1v_usd: DV01 da 1ª volta em USD usando a PTAX do dia.
        - dv01_2v_usd: DV01 da 2ª volta em USD usando a PTAX do dia.
        - dv01_total_usd: DV01 total das duas voltas em USD usando a PTAX do dia.
        - pu_minimo: Preço Unitário mínimo aceito no leilão.
        - pu_medio: Preço Unitário médio ponderado das propostas aceitas.
        - tipo_pu_medio: Indica se o PU médio é "original" (fornecido pela API) ou
            "calculado" (recalculado pela função).
        - taxa_media: Taxa de juros média das propostas aceitas (em formato decimal).
        - taxa_maxima: Taxa de juros máxima aceita no leilão (taxa de corte, em formato
            decimal).

    Retorna um DataFrame do Pandas vazio se ocorrer um erro na requisição, no
    processamento, ou se não houver dados para a data especificada.
    """
    if has_null_args(auction_date):
        logger.info("No auction date provided.")
        return pl.DataFrame()
    try:
        auction_date = cv.convert_dates(auction_date)
        data = _fetch_auction_data(auction_date)
        if not data:
            logger.info(f"No auction data available for {auction_date}.")
            return pl.DataFrame()
        df = _transform_raw_data(data)
        df = _add_duration(df)
        df = _add_dv01(df)
        df = _add_dv01_usd(df)
        df = _add_avg_maturity(df)
        df = df.select(FINAL_COLUMN_ORDER)
        return df

    except requests.exceptions.RequestException as e:
        logger.error(f"An error occurred during the API request: {e}")
        return pl.DataFrame()
    except ValueError as e:
        logger.error(f"An error occurred while parsing the JSON response: {e}")
        return pl.DataFrame()

`benchmarks(bond_type=None, include_history=False)`

Fetches benchmark data for Brazilian Treasury Bonds from the TN API.

This function retrieves current or historical benchmark data for various Brazilian Treasury bond types (e.g., LTN, LFT, NTN-B). The data is sourced directly from the official Tesouro Nacional API.

Parameters:

Name	Type	Description	Default
`include_history`	`bool`	If `True`, includes historical benchmark data. If `False` (default), only current benchmarks are returned.	`False`

Returns:

Type Description

DataFrame

pl.DataFrame: A Polars DataFrame containing the benchmark data. The DataFrame includes the following columns: * BondType (str): The type of the bond (e.g., 'LTN', 'LFT', 'NTN-B'). * MaturityDate (datetime.date): The maturity date of the benchmark. * Benchmark (str): The name or identifier of the benchmark (e.g., 'LFT 3 anos'). * StartDate (datetime.date): The start date for the benchmark's period. * EndDate (datetime.date): The end date for the benchmark's period.

Notes

Data is sourced from the official Tesouro Nacional (Brazilian Treasury) API.
An retry mechanism is implemented for SSL certificate verification errors.
The API documentation can be found at: https://portal-conhecimento.tesouro.gov.br/catalogo-componentes/api-leil%C3%B5es
Rows with any NaN values are dropped before returning the DataFrame.

Examples:

>>> from pyield import tn
>>> df_current = tn.benchmarks()
>>> # Get historical benchmarks
>>> tn.benchmarks(bond_type="LFT", include_history=True).head()
shape: (5, 5)
┌──────────┬──────────────┬────────────┬────────────┬────────────┐
│ BondType ┆ MaturityDate ┆ Benchmark  ┆ StartDate  ┆ EndDate    │
│ ---      ┆ ---          ┆ ---        ┆ ---        ┆ ---        │
│ str      ┆ date         ┆ str        ┆ date       ┆ date       │
╞══════════╪══════════════╪════════════╪════════════╪════════════╡
│ LFT      ┆ 2020-03-01   ┆ LFT 6 anos ┆ 2014-01-01 ┆ 2014-06-30 │
│ LFT      ┆ 2020-09-01   ┆ LFT 6 anos ┆ 2014-07-01 ┆ 2014-12-31 │
│ LFT      ┆ 2021-03-01   ┆ LFT 6 anos ┆ 2015-01-01 ┆ 2015-04-30 │
│ LFT      ┆ 2021-09-01   ┆ LFT 6 anos ┆ 2015-05-01 ┆ 2015-12-31 │
│ LFT      ┆ 2022-03-01   ┆ LFT 6 anos ┆ 2016-01-01 ┆ 2016-06-30 │
└──────────┴──────────────┴────────────┴────────────┴────────────┘

Source code in pyield/tn/benchmark.py

def benchmarks(bond_type: str = None, include_history: bool = False) -> pl.DataFrame:
    """Fetches benchmark data for Brazilian Treasury Bonds from the TN API.

    This function retrieves current or historical benchmark data for various Brazilian
    Treasury bond types (e.g., LTN, LFT, NTN-B). The data is sourced directly from the
    official Tesouro Nacional API.

    Args:
        include_history (bool, optional): If `True`, includes historical benchmark data.
            If `False` (default), only current benchmarks are returned.

    Returns:
        pl.DataFrame: A Polars DataFrame containing the benchmark data.
            The DataFrame includes the following columns:
            *   `BondType` (str): The type of the bond (e.g., 'LTN', 'LFT', 'NTN-B').
            *   `MaturityDate` (datetime.date): The maturity date of the benchmark.
            *   `Benchmark` (str): The name or identifier of the benchmark
                (e.g., 'LFT 3 anos').
            *   `StartDate` (datetime.date): The start date for the benchmark's period.
            *   `EndDate` (datetime.date): The end date for the benchmark's period.

    Notes:
        *   Data is sourced from the official Tesouro Nacional (Brazilian Treasury) API.
        *   An retry mechanism is implemented for SSL certificate verification errors.
        *   The API documentation can be found at:
            https://portal-conhecimento.tesouro.gov.br/catalogo-componentes/api-leil%C3%B5es
        *   Rows with any `NaN` values are dropped before returning the DataFrame.

    Examples:
        >>> from pyield import tn
        >>> df_current = tn.benchmarks()
        >>> # Get historical benchmarks
        >>> tn.benchmarks(bond_type="LFT", include_history=True).head()
        shape: (5, 5)
        ┌──────────┬──────────────┬────────────┬────────────┬────────────┐
        │ BondType ┆ MaturityDate ┆ Benchmark  ┆ StartDate  ┆ EndDate    │
        │ ---      ┆ ---          ┆ ---        ┆ ---        ┆ ---        │
        │ str      ┆ date         ┆ str        ┆ date       ┆ date       │
        ╞══════════╪══════════════╪════════════╪════════════╪════════════╡
        │ LFT      ┆ 2020-03-01   ┆ LFT 6 anos ┆ 2014-01-01 ┆ 2014-06-30 │
        │ LFT      ┆ 2020-09-01   ┆ LFT 6 anos ┆ 2014-07-01 ┆ 2014-12-31 │
        │ LFT      ┆ 2021-03-01   ┆ LFT 6 anos ┆ 2015-01-01 ┆ 2015-04-30 │
        │ LFT      ┆ 2021-09-01   ┆ LFT 6 anos ┆ 2015-05-01 ┆ 2015-12-31 │
        │ LFT      ┆ 2022-03-01   ┆ LFT 6 anos ┆ 2016-01-01 ┆ 2016-06-30 │
        └──────────┴──────────────┴────────────┴────────────┴────────────┘
    """
    api_data = _fetch_raw_benchmarks(include_history=include_history)
    df = _process_api_data(api_data)

    # Definir a ordenação final com base no caso de uso
    if include_history:
        # Para dados históricos, a ordem cronológica é mais útil
        sort_columns = ["StartDate", "BondType", "MaturityDate"]
    else:
        # Para dados atuais, agrupar por tipo de título é mais útil
        sort_columns = ["BondType", "MaturityDate"]
        # Filtrar apenas os dados atuais
        today = dt.now(TIMEZONE_BZ).date()
        df = df.filter(pl.lit(today).is_between(pl.col("StartDate"), pl.col("EndDate")))

    if bond_type:
        df = df.filter(pl.col("BondType") == bond_type)

    return df.select(FINAL_COLUMN_ORDER).sort(sort_columns)

`di_spreads(date, bps=False)`

Calcula o DI Spread para títulos prefixados (LTN e NTN-F) em uma data de referência.

spread = taxa indicativa do PRE - taxa de ajuste do DI

Quando bps=False a coluna retorna essa diferença em formato decimal (ex: 0.000439 ≈ 4.39 bps). Quando bps=True o valor é automaticamente multiplicado por 10_000 e exibido diretamente em basis points.

Parameters:

Name	Type	Description	Default
`date`	`DateScalar`	Data de referência para buscar as taxas.	required
`bps`	`bool`	Se True, retorna DISpread já convertido em basis points. Default False.	`False`

Returns:

Type	Description
`DataFrame`	pl.DataFrame com colunas: - BondType - MaturityDate - DISpread (decimal ou bps conforme parâmetro)

Examples:

>>> from pyield import pre
>>> pre.di_spreads("30-05-2025", bps=True)
shape: (18, 3)
┌──────────┬──────────────┬──────────┐
│ BondType ┆ MaturityDate ┆ DISpread │
│ ---      ┆ ---          ┆ ---      │
│ str      ┆ date         ┆ f64      │
╞══════════╪══════════════╪══════════╡
│ LTN      ┆ 2025-07-01   ┆ 4.39     │
│ LTN      ┆ 2025-10-01   ┆ -9.0     │
│ LTN      ┆ 2026-01-01   ┆ -4.88    │
│ LTN      ┆ 2026-04-01   ┆ -4.45    │
│ LTN      ┆ 2026-07-01   ┆ 0.81     │
│ …        ┆ …            ┆ …        │
│ NTN-F    ┆ 2027-01-01   ┆ -3.31    │
│ NTN-F    ┆ 2029-01-01   ┆ 14.21    │
│ NTN-F    ┆ 2031-01-01   ┆ 21.61    │
│ NTN-F    ┆ 2033-01-01   ┆ 11.51    │
│ NTN-F    ┆ 2035-01-01   ┆ 22.0     │
└──────────┴──────────────┴──────────┘

Source code in pyield/tn/pre.py

def di_spreads(date: DateScalar, bps: bool = False) -> pl.DataFrame:
    """
    Calcula o DI Spread para títulos prefixados (LTN e NTN-F) em uma data de referência.

    spread = taxa indicativa do PRE - taxa de ajuste do DI

    Quando ``bps=False`` a coluna retorna essa diferença em formato decimal
    (ex: 0.000439 ≈ 4.39 bps). Quando ``bps=True`` o valor é automaticamente
    multiplicado por 10_000 e exibido diretamente em basis points.

    Args:
        date (DateScalar): Data de referência para buscar as taxas.
        bps (bool): Se True, retorna DISpread já convertido em basis points.
            Default False.

    Returns:
        pl.DataFrame com colunas:
            - BondType
            - MaturityDate
            - DISpread (decimal ou bps conforme parâmetro)

    Examples:
        >>> from pyield import pre
        >>> pre.di_spreads("30-05-2025", bps=True)
        shape: (18, 3)
        ┌──────────┬──────────────┬──────────┐
        │ BondType ┆ MaturityDate ┆ DISpread │
        │ ---      ┆ ---          ┆ ---      │
        │ str      ┆ date         ┆ f64      │
        ╞══════════╪══════════════╪══════════╡
        │ LTN      ┆ 2025-07-01   ┆ 4.39     │
        │ LTN      ┆ 2025-10-01   ┆ -9.0     │
        │ LTN      ┆ 2026-01-01   ┆ -4.88    │
        │ LTN      ┆ 2026-04-01   ┆ -4.45    │
        │ LTN      ┆ 2026-07-01   ┆ 0.81     │
        │ …        ┆ …            ┆ …        │
        │ NTN-F    ┆ 2027-01-01   ┆ -3.31    │
        │ NTN-F    ┆ 2029-01-01   ┆ 14.21    │
        │ NTN-F    ┆ 2031-01-01   ┆ 21.61    │
        │ NTN-F    ┆ 2033-01-01   ┆ 11.51    │
        │ NTN-F    ┆ 2035-01-01   ┆ 22.0     │
        └──────────┴──────────────┴──────────┘
    """
    # Fetch bond rates, filtering for LTN and NTN-F types
    df = (
        tpf.tpf_data(date, "PRE")
        .with_columns(DISpread=pl.col("IndicativeRate") - pl.col("DIRate"))
        .select("BondType", "MaturityDate", "DISpread")
        .sort("BondType", "MaturityDate")
    )

    if bps:
        df = df.with_columns(pl.col("DISpread") * 10_000)

    return df