Pular para conteúdo

Visão Geral

auction(auction_date)

Consulta e processa os resultados de leilões de títulos do Tesouro Nacional.

Busca os dados da API do Tesouro para a(s) data(s) informada(s) e retorna um DataFrame estruturado com quantidades, financeiros, taxas de colocação, duration e DV01.

Parameters:

Name Type Description Default
auction_date DateLike | Sequence[DateLike]

Data ou sequência de datas do leilão em qualquer formato aceito por DateLike (ex: "DD-MM-YYYY", datetime.date, ou lista desses formatos).

 required

Returns:

Type Description
DataFrame

DataFrame com os dados processados do leilão. Em caso de erro na
DataFrame

requisição, no processamento ou se não houver dados para a data
DataFrame

especificada, retorna DataFrame vazio.
Output Columns
  • data_1v (Date): data de realização do leilão (1ª volta).
  • data_liquidacao_1v (Date): data de liquidação financeira da 1ª volta.
  • data_liquidacao_2v (Date): data de liquidação financeira da 2ª volta (se houver).
  • numero_edital (Int64): número do edital que rege o leilão.
  • tipo_leilao (String): tipo da operação (ex: "Venda", "Compra").
  • titulo (String): código do título público leiloado (ex: "NTN-B", "LFT").
  • benchmark (String): descrição de referência do título (ex: "NTN-B 3 anos").
  • data_vencimento (Date): data de vencimento do título.
  • dias_uteis (Int32): dias úteis entre a liquidação (1v) e o vencimento.
  • dias_corridos (Int32): prazo em dias corridos entre liquidação e vencimento.
  • duration (Float64): Duração de Macaulay em anos, calculada entre a liquidação da 1ª volta e o vencimento.
  • prazo_medio (Float64): maturidade média em anos, conforme metodologia do Tesouro Nacional.
  • quantidade_ofertada_1v (Int64): quantidade de títulos ofertados na 1ª volta.
  • quantidade_ofertada_2v (Int64): quantidade de títulos ofertados na 2ª volta.
  • quantidade_aceita_1v (Int64): quantidade de propostas aceitas na 1ª volta.
  • quantidade_aceita_2v (Int64): quantidade de títulos aceitos na 2ª volta.
  • quantidade_aceita_total (Int64): soma das quantidades aceitas nas duas voltas.
  • financeiro_ofertado_1v (Float64): financeiro ofertado na 1ª volta (BRL).
  • financeiro_ofertado_2v (Float64): financeiro ofertado na 2ª volta (BRL).
  • financeiro_ofertado_total (Float64): financeiro total ofertado (BRL).
  • financeiro_aceito_1v (Float64): financeiro aceito na 1ª volta (BRL).
  • financeiro_aceito_2v (Float64): financeiro aceito na 2ª volta (BRL).
  • financeiro_aceito_total (Float64): soma do financeiro aceito nas duas voltas (BRL).
  • quantidade_bcb (Int64): quantidade de títulos adquirida pelo Banco Central.
  • financeiro_bcb (Int64): financeiro adquirido pelo Banco Central.
  • colocacao_1v (Float64): taxa de colocação da 1ª volta (aceita / ofertada).
  • colocacao_2v (Float64): taxa de colocação da 2ª volta (aceita / ofertada).
  • colocacao_total (Float64): taxa de colocação total (aceita / ofertada).
  • dv01_1v (Float64): DV01 da 1ª volta em BRL.
  • dv01_2v (Float64): DV01 da 2ª volta em BRL.
  • dv01_total (Float64): DV01 total do leilão em BRL.
  • ptax (Float64): taxa PTAX (venda) utilizada na conversão do DV01 para USD.
  • dv01_1v_usd (Float64): DV01 da 1ª volta em USD (PTAX do dia).
  • dv01_2v_usd (Float64): DV01 da 2ª volta em USD (PTAX do dia).
  • dv01_total_usd (Float64): DV01 total em USD (PTAX do dia).
  • pu_minimo (Float64): preço unitário mínimo aceito no leilão.
  • pu_medio (Float64): preço unitário médio ponderado das propostas aceitas.
  • tipo_pu_medio (String): indica se o PU médio é "original" (da API) ou "calculado" (recalculado pela função).
  • taxa_media (Float64): taxa de juros média aceita (em formato decimal).
  • taxa_maxima (Float64): taxa de juros máxima aceita, taxa de corte (decimal).
Source code in pyield/tn/auctions.py 
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
def auction(auction_date: DateLike | Sequence[DateLike]) -> pl.DataFrame:
    """Consulta e processa os resultados de leilões de títulos do Tesouro Nacional.

    Busca os dados da API do Tesouro para a(s) data(s) informada(s) e retorna
    um DataFrame estruturado com quantidades, financeiros, taxas de colocação,
    duration e DV01.

    Args:
        auction_date: Data ou sequência de datas do leilão em qualquer
            formato aceito por DateLike (ex: "DD-MM-YYYY", datetime.date,
            ou lista desses formatos).

    Returns:
        DataFrame com os dados processados do leilão. Em caso de erro na
        requisição, no processamento ou se não houver dados para a data
        especificada, retorna DataFrame vazio.

    Output Columns:
        - data_1v (Date): data de realização do leilão (1ª volta).
        - data_liquidacao_1v (Date): data de liquidação financeira da 1ª volta.
        - data_liquidacao_2v (Date): data de liquidação financeira da 2ª volta
            (se houver).
        - numero_edital (Int64): número do edital que rege o leilão.
        - tipo_leilao (String): tipo da operação (ex: "Venda", "Compra").
        - titulo (String): código do título público leiloado (ex: "NTN-B", "LFT").
        - benchmark (String): descrição de referência do título (ex: "NTN-B 3 anos").
        - data_vencimento (Date): data de vencimento do título.
        - dias_uteis (Int32): dias úteis entre a liquidação (1v) e o vencimento.
        - dias_corridos (Int32): prazo em dias corridos entre liquidação e vencimento.
        - duration (Float64): Duração de Macaulay em anos, calculada entre a liquidação
            da 1ª volta e o vencimento.
        - prazo_medio (Float64): maturidade média em anos, conforme metodologia do
            Tesouro Nacional.
        - quantidade_ofertada_1v (Int64): quantidade de títulos ofertados na 1ª volta.
        - quantidade_ofertada_2v (Int64): quantidade de títulos ofertados na 2ª volta.
        - quantidade_aceita_1v (Int64): quantidade de propostas aceitas na 1ª volta.
        - quantidade_aceita_2v (Int64): quantidade de títulos aceitos na 2ª volta.
        - quantidade_aceita_total (Int64): soma das quantidades aceitas nas duas voltas.
        - financeiro_ofertado_1v (Float64): financeiro ofertado na 1ª volta (BRL).
        - financeiro_ofertado_2v (Float64): financeiro ofertado na 2ª volta (BRL).
        - financeiro_ofertado_total (Float64): financeiro total ofertado (BRL).
        - financeiro_aceito_1v (Float64): financeiro aceito na 1ª volta (BRL).
        - financeiro_aceito_2v (Float64): financeiro aceito na 2ª volta (BRL).
        - financeiro_aceito_total (Float64): soma do financeiro aceito nas
            duas voltas (BRL).
        - quantidade_bcb (Int64): quantidade de títulos adquirida pelo Banco Central.
        - financeiro_bcb (Int64): financeiro adquirido pelo Banco Central.
        - colocacao_1v (Float64): taxa de colocação da 1ª volta (aceita / ofertada).
        - colocacao_2v (Float64): taxa de colocação da 2ª volta (aceita / ofertada).
        - colocacao_total (Float64): taxa de colocação total (aceita / ofertada).
        - dv01_1v (Float64): DV01 da 1ª volta em BRL.
        - dv01_2v (Float64): DV01 da 2ª volta em BRL.
        - dv01_total (Float64): DV01 total do leilão em BRL.
        - ptax (Float64): taxa PTAX (venda) utilizada na conversão do DV01 para USD.
        - dv01_1v_usd (Float64): DV01 da 1ª volta em USD (PTAX do dia).
        - dv01_2v_usd (Float64): DV01 da 2ª volta em USD (PTAX do dia).
        - dv01_total_usd (Float64): DV01 total em USD (PTAX do dia).
        - pu_minimo (Float64): preço unitário mínimo aceito no leilão.
        - pu_medio (Float64): preço unitário médio ponderado das propostas aceitas.
        - tipo_pu_medio (String): indica se o PU médio é "original" (da API) ou
            "calculado" (recalculado pela função).
        - taxa_media (Float64): taxa de juros média aceita (em formato decimal).
        - taxa_maxima (Float64): taxa de juros máxima aceita, taxa de corte (decimal).
    """
    if any_is_empty(auction_date):
        return pl.DataFrame()

    datas: Sequence[DateLike] = (
        auction_date if is_collection(auction_date) else [auction_date]  # type: ignore[assignment]
    )
    resultados = [_processar_data_unica(d) for d in datas]
    resultados = [df for df in resultados if not df.is_empty()]
    if not resultados:
        return pl.DataFrame()
    return pl.concat(resultados)

benchmarks(bond_type=None, include_history=False)

Busca benchmarks de títulos públicos brasileiros na API do TN.

Recupera dados atuais ou históricos de benchmarks para títulos do Tesouro Nacional (ex.: LTN, LFT, NTN-B).

Parameters:

Name Type Description Default
bond_type str | None

Tipo do título a filtrar (ex.: "LFT").

 None
include_history bool

Se True, inclui histórico; se False (padrão), retorna apenas benchmarks vigentes.

 False

Returns:

Type Description
DataFrame

DataFrame com os benchmarks, ou DataFrame vazio.
Output Columns
  • titulo (String): tipo do título (ex.: "LTN", "LFT").
  • data_vencimento (Date): data de vencimento do benchmark.
  • benchmark (String): nome/identificador do benchmark.
  • data_inicio (Date): data de início da vigência.
  • data_fim (Date): data de término da vigência.
Notes

Dados obtidos da API oficial do Tesouro Nacional. Documentação da API: https://portal-conhecimento.tesouro.gov.br/catalogo-componentes/api-leil%C3%B5es

Examples:

>>> from pyield import tn
>>> df_current = tn.benchmarks()
>>> # Benchmarks históricos
>>> tn.benchmarks(bond_type="LFT", include_history=True).head()
shape: (5, 5)
┌────────┬─────────────────┬────────────┬─────────────┬────────────┐
│ titulo ┆ data_vencimento ┆ benchmark  ┆ data_inicio ┆ data_fim   │
│ ---    ┆ ---             ┆ ---        ┆ ---         ┆ ---        │
│ 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 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def benchmarks(
    bond_type: str | None = None, include_history: bool = False
) -> pl.DataFrame:
    """Busca benchmarks de títulos públicos brasileiros na API do TN.

    Recupera dados atuais ou históricos de benchmarks para títulos do
    Tesouro Nacional (ex.: LTN, LFT, NTN-B).

    Args:
        bond_type: Tipo do título a filtrar (ex.: "LFT").
        include_history: Se ``True``, inclui histórico; se ``False``
            (padrão), retorna apenas benchmarks vigentes.

    Returns:
        DataFrame com os benchmarks, ou DataFrame vazio.

    Output Columns:
        * titulo (String): tipo do título (ex.: "LTN", "LFT").
        * data_vencimento (Date): data de vencimento do benchmark.
        * benchmark (String): nome/identificador do benchmark.
        * data_inicio (Date): data de início da vigência.
        * data_fim (Date): data de término da vigência.

    Notes:
        Dados obtidos da API oficial do Tesouro Nacional.
        Documentação da API:
        https://portal-conhecimento.tesouro.gov.br/catalogo-componentes/api-leil%C3%B5es

    Examples:
        >>> from pyield import tn
        >>> df_current = tn.benchmarks()
        >>> # Benchmarks históricos
        >>> tn.benchmarks(bond_type="LFT", include_history=True).head()
        shape: (5, 5)
        ┌────────┬─────────────────┬────────────┬─────────────┬────────────┐
        │ titulo ┆ data_vencimento ┆ benchmark  ┆ data_inicio ┆ data_fim   │
        │ ---    ┆ ---             ┆ ---        ┆ ---         ┆ ---        │
        │ 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 │
        └────────┴─────────────────┴────────────┴─────────────┴────────────┘
    """
    dados = _buscar_json_api(include_history)
    df = _parsear_df(dados)
    if df.is_empty():
        return pl.DataFrame()
    df = _processar_df(df)

    if include_history:
        colunas_ordenacao = ["data_inicio", "titulo", "data_vencimento"]
    else:
        colunas_ordenacao = ["titulo", "data_vencimento"]
        hoje = clock.today()
        df = df.filter(pl.lit(hoje).is_between("data_inicio", "data_fim"))

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

    return df.sort(colunas_ordenacao)

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 DateLike

Data de referência para buscar as taxas.

 required
bps bool

Se True, retorna spread_di já convertido em basis points. Padrão False.

 False

Returns:

Type Description
DataFrame

pl.DataFrame: DataFrame com as colunas do spread.
Output Columns
  • titulo (String): Tipo do título.
  • data_vencimento (Date): Data de vencimento.
  • spread_di (Float64): Spread em decimal ou bps conforme parâmetro (também conhecido como prêmio).

Examples:

>>> from pyield import pre
>>> pre.di_spreads("30-05-2025", bps=True)
shape: (18, 3)
┌────────┬─────────────────┬───────────┐
│ titulo ┆ data_vencimento ┆ spread_di │
│ ---    ┆ ---             ┆ ---       │
│ 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 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
def di_spreads(date: DateLike, 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 (DateLike): Data de referência para buscar as taxas.
        bps (bool): Se True, retorna spread_di já convertido em basis points.
            Padrão False.

    Returns:
        pl.DataFrame: DataFrame com as colunas do spread.

    Output Columns:
        - titulo (String): Tipo do título.
        - data_vencimento (Date): Data de vencimento.
        - spread_di (Float64): Spread em decimal ou bps conforme parâmetro
            (também conhecido como prêmio).

    Examples:
        >>> from pyield import pre
        >>> pre.di_spreads("30-05-2025", bps=True)
        shape: (18, 3)
        ┌────────┬─────────────────┬───────────┐
        │ titulo ┆ data_vencimento ┆ spread_di │
        │ ---    ┆ ---             ┆ ---       │
        │ 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      │
        └────────┴─────────────────┴───────────┘
    """
    # Busca taxas dos títulos (LTN e NTN-F) e adiciona taxa_di
    df = utils.obter_tpf(date, "PRE").select(
        "titulo", "data_vencimento", "taxa_indicativa"
    )
    if df.is_empty():
        return df.select(
            pl.lit("").alias("titulo"),
            pl.lit(None, dtype=pl.Date).alias("data_vencimento"),
            pl.lit(None, dtype=pl.Float64).alias("spread_di"),
        ).clear()
    data_ref = cv.converter_datas(date)
    df = utils.adicionar_taxa_di(df, data_ref)
    df = (
        df.with_columns(spread_di=pl.col("taxa_indicativa") - pl.col("taxa_di"))
        .select("titulo", "data_vencimento", "spread_di")
        .sort("titulo", "data_vencimento")
    )

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

    return df