Pular para conteúdo

Títulos Públicos Federais (TPF)

Porta de entrada principal para dados de mercado de títulos públicos: taxas indicativas, vencimentos, estoque, negociações secundárias, leilões, benchmarks e Relatório Mensal da Dívida (RMD).

Para precificação e análise por tipo de título (cotação, duration, prêmio), consulte as páginas individuais: LFT, LTN, NTN-B, NTN-F, etc.

Títulos Públicos Federais.

benchmarks(titulo=None, incluir_historico=False)

Busca benchmarks de títulos públicos brasileiros.

Fonte: API do Tesouro Nacional.

Parameters:

Name Type Description Default
titulo str | None

Tipo do título a filtrar (ex.: "LFT"). Se None, retorna todos os títulos.

 None
incluir_historico bool

Se True, inclui benchmarks históricos; se False (padrão), retorna apenas benchmarks vigentes (on-the-run).

 False

Returns:

Type Description
DataFrame

DataFrame Polars com os benchmarks. Retorna DataFrame vazio se
DataFrame

não houver dados.
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

Documentação da API: https://portal-conhecimento.tesouro.gov.br/catalogo-componentes/api-leil%C3%B5es

Examples:

>>> df = yd.tpf.benchmarks(incluir_historico=False)
Source code in pyield/tpf/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
def benchmarks(
    titulo: str | None = None,
    incluir_historico: bool = False,
) -> pl.DataFrame:
    """Busca benchmarks de títulos públicos brasileiros.

    Fonte: API do Tesouro Nacional.

    Args:
        titulo: Tipo do título a filtrar (ex.: ``"LFT"``). Se ``None``,
            retorna todos os títulos.
        incluir_historico: Se ``True``, inclui benchmarks históricos; se
            ``False`` (padrão), retorna apenas benchmarks vigentes
            (on-the-run).

    Returns:
        DataFrame Polars com os benchmarks. Retorna DataFrame vazio se
        não houver dados.

    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:
        Documentação da API:
        https://portal-conhecimento.tesouro.gov.br/catalogo-componentes/api-leil%C3%B5es

    Examples:
        >>> df = yd.tpf.benchmarks(incluir_historico=False)
    """
    dados = _buscar_json_api(incluir_historico)
    df = _parsear_df(dados)
    if df.is_empty():
        return pl.DataFrame()
    df = _processar_df(df)

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

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

    return df.sort(colunas_ordenacao)

curva_pre(data)

Constrói a curva PRE (taxas zero cupom prefixadas).

Combina taxas de LTN (já zero cupom) com taxas spot derivadas de NTN-F via bootstrap. O resultado é a curva de juros prefixada brasileira expressa em taxas zero cupom.

Fonte: ANBIMA (taxas indicativas de LTN e NTN-F).

Parameters:

Name Type Description Default
data DateLike

Data de referência.

 required

Returns:

Type Description
DataFrame

DataFrame com a curva PRE para a data solicitada. Retorna DataFrame
DataFrame

vazio se não houver dados de LTN disponíveis.
Output Columns
  • data_vencimento (Date): data de vencimento do vértice.
  • dias_uteis (Int64): dias úteis entre a data de referência e o vencimento.
  • taxa_zero (Float64): taxa zero cupom anualizada (base 252).

Raises:

Type Description
ValueError

Se houver NTN-F sem dados de LTN para bootstrap.

Examples:

>>> yd.tpf.curva_pre("18-06-2025")
shape: (17, 3)
┌─────────────────┬────────────┬───────────┐
│ data_vencimento ┆ dias_uteis ┆ taxa_zero │
│ ---             ┆ ---        ┆ ---       │
│ date            ┆ i64        ┆ f64       │
╞═════════════════╪════════════╪═══════════╡
│ 2025-07-01      ┆ 8          ┆ 0.14835   │
│ 2025-10-01      ┆ 74         ┆ 0.147463  │
│ 2026-01-01      ┆ 138        ┆ 0.147752  │
│ 2026-04-01      ┆ 199        ┆ 0.147947  │
│ 2026-07-01      ┆ 260        ┆ 0.147069  │
│ …               ┆ …          ┆ …         │
│ 2030-01-01      ┆ 1135       ┆ 0.137279  │
│ 2031-01-01      ┆ 1387       ┆ 0.138154  │
│ 2032-01-01      ┆ 1639       ┆ 0.13876   │
│ 2033-01-01      ┆ 1891       ┆ 0.1393    │
│ 2035-01-01      ┆ 2390       ┆ 0.141068  │
└─────────────────┴────────────┴───────────┘
Source code in pyield/tpf/pre.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 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
def curva_pre(data: DateLike) -> pl.DataFrame:
    """Constrói a curva PRE (taxas zero cupom prefixadas).

    Combina taxas de LTN (já zero cupom) com taxas spot derivadas de NTN-F
    via bootstrap. O resultado é a curva de juros prefixada brasileira expressa
    em taxas zero cupom.

    Fonte: ANBIMA (taxas indicativas de LTN e NTN-F).

    Args:
        data: Data de referência.

    Returns:
        DataFrame com a curva PRE para a data solicitada. Retorna DataFrame
        vazio se não houver dados de LTN disponíveis.

    Output Columns:
        * data_vencimento (Date): data de vencimento do vértice.
        * dias_uteis (Int64): dias úteis entre a data de referência e o vencimento.
        * taxa_zero (Float64): taxa zero cupom anualizada (base 252).

    Raises:
        ValueError: Se houver NTN-F sem dados de LTN para bootstrap.

    Examples:
        >>> yd.tpf.curva_pre("18-06-2025")
        shape: (17, 3)
        ┌─────────────────┬────────────┬───────────┐
        │ data_vencimento ┆ dias_uteis ┆ taxa_zero │
        │ ---             ┆ ---        ┆ ---       │
        │ date            ┆ i64        ┆ f64       │
        ╞═════════════════╪════════════╪═══════════╡
        │ 2025-07-01      ┆ 8          ┆ 0.14835   │
        │ 2025-10-01      ┆ 74         ┆ 0.147463  │
        │ 2026-01-01      ┆ 138        ┆ 0.147752  │
        │ 2026-04-01      ┆ 199        ┆ 0.147947  │
        │ 2026-07-01      ┆ 260        ┆ 0.147069  │
        │ …               ┆ …          ┆ …         │
        │ 2030-01-01      ┆ 1135       ┆ 0.137279  │
        │ 2031-01-01      ┆ 1387       ┆ 0.138154  │
        │ 2032-01-01      ┆ 1639       ┆ 0.13876   │
        │ 2033-01-01      ┆ 1891       ┆ 0.1393    │
        │ 2035-01-01      ┆ 2390       ┆ 0.141068  │
        └─────────────────┴────────────┴───────────┘
    """
    # Busca dados de LTN (zero cupom)
    df_ltn = utils.obter_tpf(data, "LTN").select("data_vencimento", "taxa_indicativa")

    # Busca dados de NTN-F (com cupom)
    df_ntnf = utils.obter_tpf(data, "NTN-F").select(
        "data_vencimento", "taxa_indicativa"
    )

    # Verifica se há dados para ambos os tipos
    if df_ltn.is_empty() and df_ntnf.is_empty():
        return pl.DataFrame(
            schema={
                "data_vencimento": pl.Date,
                "dias_uteis": pl.Int64,
                "taxa_zero": pl.Float64,
            }
        )

    # Se só há NTN-F, não é possível fazer bootstrap sem LTN
    if df_ltn.is_empty():
        raise ValueError(
            "Não é possível construir a curva PRE sem taxas de LTN para bootstrap"
        )

    # Se só há LTN, retorna direto (LTN já são zero cupom)
    if df_ntnf.is_empty():
        df = _processar_ltn_adicionais(data, df_ltn)
    else:
        # Usa spot_rates de NTN-F para calcular zero cupom
        df_spots = ntnf.taxas_zero(
            data_liquidacao=data,
            vencimentos_ltn=df_ltn["data_vencimento"],
            taxas_ltn=df_ltn["taxa_indicativa"],
            vencimentos_ntnf=df_ntnf["data_vencimento"],
            taxas_ntnf=df_ntnf["taxa_indicativa"],
            incluir_cupons=False,
        )

        # Encontra vencimentos de LTN que não estão no resultado de NTN-F
        ltn_mask = ~df_ltn["data_vencimento"].is_in(
            df_spots["data_vencimento"].to_list()
        )
        ltn_not_in_ntnf = df_ltn.filter(ltn_mask)

        if not ltn_not_in_ntnf.is_empty():
            # Processa vencimentos de LTN adicionais
            ltn_subset = _processar_ltn_adicionais(
                data,
                ltn_not_in_ntnf,
            )

            # Combina LTN e NTN-F
            df = pl.concat([df_spots, ltn_subset])
        else:
            df = df_spots

    # Validação final
    _validar_resultado_final(df)

    # Ordena por vencimento
    return df.sort("data_vencimento")

estoque(data)

Busca dados de estoque de TPFs.

Fonte: IMA-Q da ANBIMA. Contém quantidade em mercado, valor de mercado e variação diária da quantidade dos títulos.

Parameters:

Name Type Description Default
data DateLike

Data de referência.

 required

Returns:

Type Description
DataFrame

DataFrame Polars com dados de estoque. Retorna DataFrame vazio se a
DataFrame

data for inválida ou não houver dados.
Output Columns
  • data_referencia (Date): data de referência dos dados.
  • titulo (String): tipo do título público.
  • data_vencimento (Date): data de vencimento do título.
  • codigo_selic (Int64): código SELIC do título.
  • isin (String): código ISIN.
  • pu (Float64): preço unitário do título em reais.
  • quantidade_mercado (Int64): quantidade em mercado.
  • valor_mercado (Int64): valor de mercado em reais.
  • variacao_quantidade (Int64): variação diária da quantidade.
  • status_titulo (String): status do título.

Examples:

>>> import datetime as dt
>>> data = yd.du.deslocar(dt.date.today(), -2)
>>> df = yd.tpf.estoque(data)
>>> df.shape[0] > 0
True
Source code in pyield/anbima/imaq.py 
128
129
130
131
132
133
134
135
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
def estoque(data: DateLike) -> pl.DataFrame:
    """Busca dados de estoque de TPFs.

    Fonte: IMA-Q da ANBIMA. Contém quantidade em mercado, valor de mercado
    e variação diária da quantidade dos títulos.

    Args:
        data: Data de referência.

    Returns:
        DataFrame Polars com dados de estoque. Retorna DataFrame vazio se a
        data for inválida ou não houver dados.

    Output Columns:
        * data_referencia (Date): data de referência dos dados.
        * titulo (String): tipo do título público.
        * data_vencimento (Date): data de vencimento do título.
        * codigo_selic (Int64): código SELIC do título.
        * isin (String): código ISIN.
        * pu (Float64): preço unitário do título em reais.
        * quantidade_mercado (Int64): quantidade em mercado.
        * valor_mercado (Int64): valor de mercado em reais.
        * variacao_quantidade (Int64): variação diária da quantidade.
        * status_titulo (String): status do título.

    Examples:
        >>> import datetime as dt
        >>> data = yd.du.deslocar(dt.date.today(), -2)
        >>> df = yd.tpf.estoque(data)
        >>> df.shape[0] > 0
        True
    """
    data = cv.converter_datas(data)
    if not cv.data_referencia_valida(data):
        return pl.DataFrame()

    url_content = _buscar_conteudo_url(data)
    if not url_content:
        return pl.DataFrame()

    df = _parsear_tabelas_html(url_content)
    if df.is_empty():
        return pl.DataFrame()
    return _processar_df(df, data)

premio_pre(data, pontos_base=False)

Calcula o prêmio dos títulos prefixados (LTN e NTN-F) sobre o DI.

Em linguagem de mercado, esse valor é chamado de prêmio. Em termos descritivos, trata-se do spread sobre o DI.

Definição do prêmio

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

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

Parameters:

Name Type Description Default
data DateLike

Data da consulta para buscar as taxas.

 required
pontos_base bool

Se True, retorna o prêmio já convertido em basis points. Padrão False.

 False

Returns:

Type Description
DataFrame

DataFrame com as colunas do prêmio. Retorna DataFrame vazio se
DataFrame

não houver dados.
Output Columns
  • titulo (String): tipo do título.
  • data_vencimento (Date): data de vencimento.
  • premio (Float64): prêmio em decimal ou bps conforme parâmetro (spread sobre o DI).

Examples:

>>> yd.tpf.premio_pre("30-05-2025", pontos_base=True)
shape: (18, 3)
┌────────┬─────────────────┬────────┐
│ titulo ┆ data_vencimento ┆ premio │
│ ---    ┆ ---             ┆ ---    │
│ 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/tpf/utils.py 
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
def premio_pre(
    data: DateLike,
    pontos_base: bool = False,
) -> pl.DataFrame:
    """Calcula o prêmio dos títulos prefixados (LTN e NTN-F) sobre o DI.

    Em linguagem de mercado, esse valor é chamado de prêmio. Em termos
    descritivos, trata-se do spread sobre o DI.

    Definição do prêmio:
        premio = taxa indicativa do PRE - taxa de ajuste do DI

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

    Args:
        data: Data da consulta para buscar as taxas.
        pontos_base: Se True, retorna o prêmio já convertido em basis
            points. Padrão False.

    Returns:
        DataFrame com as colunas do prêmio. Retorna DataFrame vazio se
        não houver dados.

    Output Columns:
        * titulo (String): tipo do título.
        * data_vencimento (Date): data de vencimento.
        * premio (Float64): prêmio em decimal ou bps conforme parâmetro
            (spread sobre o DI).

    Examples:
        >>> yd.tpf.premio_pre("30-05-2025", pontos_base=True)
        shape: (18, 3)
        ┌────────┬─────────────────┬────────┐
        │ titulo ┆ data_vencimento ┆ premio │
        │ ---    ┆ ---             ┆ ---    │
        │ 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   │
        └────────┴─────────────────┴────────┘
    """
    df = obter_tpf(data, "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("premio"),
        ).clear()
    data_ref = cv.converter_datas(data)
    df = adicionar_taxa_di(df, data_ref)
    df = (
        df.with_columns(premio=pl.col("taxa_indicativa") - pl.col("taxa_di"))
        .select("titulo", "data_vencimento", "premio")
        .sort("titulo", "data_vencimento")
    )

    if pontos_base:
        df = df.with_columns(pl.col("premio") * 10_000)

    return df

secundario_intradia()

Busca dados intradia do mercado secundário de TPFs.

Fonte: Banco Central do Brasil, sistema SELIC. Os dados ficam disponíveis apenas durante o horário do SELIC (09:00-22:00 BRT) em dias úteis.

Returns:

Type Description
DataFrame

DataFrame Polars com negociações intradia do mercado secundário.
DataFrame

Retorna DataFrame vazio fora do horário do SELIC.
Output Columns
  • data_hora_consulta (Datetime): data e hora da consulta.
  • data_liquidacao (Date): data de liquidação à vista.
  • titulo (String): sigla do título público.
  • codigo_selic (Int64): código SELIC do título.
  • data_vencimento (Date): data de vencimento do título.
  • pu_minimo (Float64): menor preço negociado.
  • pu_medio (Float64): preço médio negociado.
  • pu_maximo (Float64): maior preço negociado.
  • pu_ultimo (Float64): último preço negociado.
  • taxa_minima (Float64): menor taxa negociada.
  • taxa_media (Float64): taxa média negociada.
  • taxa_maxima (Float64): maior taxa negociada.
  • taxa_ultima (Float64): última taxa negociada.
  • operacoes (Int64): total de operações liquidadas.
  • quantidade (Int64): quantidade total de títulos negociados.
  • financeiro (Float64): valor financeiro total negociado.
  • operacoes_corretagem (Int64): operações via corretagem.
  • quantidade_corretagem (Int64): títulos via corretagem.
  • termo_pu_minimo (Float64): menor preço a termo negociado.
  • termo_pu_medio (Float64): preço médio a termo negociado.
  • termo_pu_ultimo (Float64): último preço a termo negociado.
  • termo_pu_maximo (Float64): maior preço a termo negociado.
  • termo_taxa_ultima (Float64): última taxa a termo negociada.
  • termo_taxa_minima (Float64): menor taxa a termo negociada.
  • termo_taxa_media (Float64): taxa média a termo negociada.
  • termo_taxa_maxima (Float64): maior taxa a termo negociada.
  • termo_operacoes (Int64): total de operações a termo.
  • termo_quantidade (Int64): total de títulos a termo negociados.
  • termo_financeiro (Float64): valor financeiro total a termo.
  • termo_operacoes_corretagem (Int64): operações a termo via corretagem.
  • termo_quantidade_corretagem (Int64): títulos a termo via corretagem.

Examples:

>>> df = yd.tpf.secundario_intradia()
Source code in pyield/bc/tpf_intradia.py 
 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
138
139
140
141
142
143
144
145
146
147
148
def secundario_intradia() -> pl.DataFrame:
    """Busca dados intradia do mercado secundário de TPFs.

    Fonte: Banco Central do Brasil, sistema SELIC. Os dados ficam disponíveis
    apenas durante o horário do SELIC (09:00-22:00 BRT) em dias úteis.

    Returns:
        DataFrame Polars com negociações intradia do mercado secundário.
        Retorna DataFrame vazio fora do horário do SELIC.

    Output Columns:
        * data_hora_consulta (Datetime): data e hora da consulta.
        * data_liquidacao (Date): data de liquidação à vista.
        * titulo (String): sigla do título público.
        * codigo_selic (Int64): código SELIC do título.
        * data_vencimento (Date): data de vencimento do título.
        * pu_minimo (Float64): menor preço negociado.
        * pu_medio (Float64): preço médio negociado.
        * pu_maximo (Float64): maior preço negociado.
        * pu_ultimo (Float64): último preço negociado.
        * taxa_minima (Float64): menor taxa negociada.
        * taxa_media (Float64): taxa média negociada.
        * taxa_maxima (Float64): maior taxa negociada.
        * taxa_ultima (Float64): última taxa negociada.
        * operacoes (Int64): total de operações liquidadas.
        * quantidade (Int64): quantidade total de títulos negociados.
        * financeiro (Float64): valor financeiro total negociado.
        * operacoes_corretagem (Int64): operações via corretagem.
        * quantidade_corretagem (Int64): títulos via corretagem.
        * termo_pu_minimo (Float64): menor preço a termo negociado.
        * termo_pu_medio (Float64): preço médio a termo negociado.
        * termo_pu_ultimo (Float64): último preço a termo negociado.
        * termo_pu_maximo (Float64): maior preço a termo negociado.
        * termo_taxa_ultima (Float64): última taxa a termo negociada.
        * termo_taxa_minima (Float64): menor taxa a termo negociada.
        * termo_taxa_media (Float64): taxa média a termo negociada.
        * termo_taxa_maxima (Float64): maior taxa a termo negociada.
        * termo_operacoes (Int64): total de operações a termo.
        * termo_quantidade (Int64): total de títulos a termo negociados.
        * termo_financeiro (Float64): valor financeiro total a termo.
        * termo_operacoes_corretagem (Int64): operações a termo via corretagem.
        * termo_quantidade_corretagem (Int64): títulos a termo via corretagem.

    Examples:
        >>> df = yd.tpf.secundario_intradia()  # doctest: +SKIP
    """
    if not _mercado_selic_aberto():
        return pl.DataFrame()

    texto_bruto = _buscar_csv()
    df = _parsear_df(texto_bruto)
    return _processar_df(df)

secundario_mensal(data, extragrupo=False)

Busca dados mensais do mercado secundário de TPFs.

Fonte: Banco Central do Brasil, sistema SELIC. Baixa o arquivo mensal de negociações secundárias para o mês correspondente à data informada.

Parameters:

Name Type Description Default
data DateLike

Data de referência.

 required
extragrupo bool

Se verdadeiro, busca apenas negociações extragrupo.

 False

Returns:

Type Description
DataFrame

DataFrame Polars com dados mensais do mercado secundário.
Output Columns
  • data_liquidacao (Date): data de liquidação da negociação.
  • titulo (String): sigla do título público.
  • codigo_selic (Int64): código único no sistema SELIC.
  • isin (String): código ISIN.
  • data_emissao (Date): data de emissão do título.
  • data_vencimento (Date): data de vencimento do título.
  • operacoes (Int64): número total de operações.
  • quantidade (Int64): quantidade total negociada.
  • financeiro (Float64): valor financeiro negociado.
  • pu_minimo (Float64): preço unitário mínimo.
  • pu_medio (Float64): preço unitário médio.
  • pu_maximo (Float64): preço unitário máximo.
  • pu_lastro (Float64): preço unitário de lastro.
  • valor_par (Float64): valor par do título.
  • taxa_minima (Float64): taxa mínima.
  • taxa_media (Float64): taxa média.
  • taxa_maxima (Float64): taxa máxima.
  • operacoes_corretagem (Int64): operações com corretagem.
  • quantidade_corretagem (Int64): quantidade com corretagem.

Examples:

>>> df = yd.tpf.secundario_mensal("07-01-2025", extragrupo=True)
Source code in pyield/bc/tpf_mensal.py 
 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
138
139
140
141
142
143
144
145
146
def secundario_mensal(
    data: DateLike,
    extragrupo: bool = False,
) -> pl.DataFrame:
    """Busca dados mensais do mercado secundário de TPFs.

    Fonte: Banco Central do Brasil, sistema SELIC. Baixa o arquivo mensal de
    negociações secundárias para o mês correspondente à data informada.

    Args:
        data: Data de referência.
        extragrupo: Se verdadeiro, busca apenas negociações extragrupo.

    Returns:
        DataFrame Polars com dados mensais do mercado secundário.

    Output Columns:
        * data_liquidacao (Date): data de liquidação da negociação.
        * titulo (String): sigla do título público.
        * codigo_selic (Int64): código único no sistema SELIC.
        * isin (String): código ISIN.
        * data_emissao (Date): data de emissão do título.
        * data_vencimento (Date): data de vencimento do título.
        * operacoes (Int64): número total de operações.
        * quantidade (Int64): quantidade total negociada.
        * financeiro (Float64): valor financeiro negociado.
        * pu_minimo (Float64): preço unitário mínimo.
        * pu_medio (Float64): preço unitário médio.
        * pu_maximo (Float64): preço unitário máximo.
        * pu_lastro (Float64): preço unitário de lastro.
        * valor_par (Float64): valor par do título.
        * taxa_minima (Float64): taxa mínima.
        * taxa_media (Float64): taxa média.
        * taxa_maxima (Float64): taxa máxima.
        * operacoes_corretagem (Int64): operações com corretagem.
        * quantidade_corretagem (Int64): quantidade com corretagem.

    Examples:
        >>> df = yd.tpf.secundario_mensal("07-01-2025", extragrupo=True)
    """
    if any_is_empty(data):
        return pl.DataFrame()
    data_alvo = converter_datas(data)
    if (data_alvo.year, data_alvo.month) > (hoje().year, hoje().month):
        return pl.DataFrame()
    url = _montar_url(data_alvo, extragrupo)
    conteudo_zip = _baixar_zip(url)
    arquivo_extraido = _descompactar_zip(conteudo_zip)
    df = _parsear_df(arquivo_extraido)
    return _processar_df(df)

taxas(data, titulo=None, completo=False)

Busca taxas e preços indicativos de TPFs.

Fonte: ANBIMA. Primeiro consulta o cache local de dados históricos; se a data não estiver no cache, busca diretamente na fonte da ANBIMA.

Parameters:

Name Type Description Default
data DateLike

Data de referência.

 required
titulo TipoTPF | None

Tipo do título público federal. Aceita LFT, NTN-B, NTN-C, LTN, NTN-F ou PRE.

 None
completo bool

Se verdadeiro, retorna os dados da ANBIMA sem cache nem filtro de colunas.

 False

Returns:

Type Description
DataFrame

DataFrame Polars com taxas e preços indicativos. Retorna DataFrame
DataFrame

vazio se não houver dados para a data.
Output Columns
  • titulo (String): tipo do título público.
  • data_referencia (Date): data de referência dos dados.
  • codigo_selic (Int64): código do título no SELIC.
  • data_base (Date): data base ou de emissão do título.
  • data_vencimento (Date): data de vencimento do título.
  • pu (Float64): preço unitário para liquidação em D0.
  • taxa_compra (Float64): taxa de compra em D0.
  • taxa_venda (Float64): taxa de venda em D0.
  • taxa_indicativa (Float64): taxa indicativa em D0.

Examples:

>>> df = yd.tpf.taxas(data="06-02-2026")
Source code in pyield/anbima/mercado_secundario.py 
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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def taxas(
    data: DateLike,
    titulo: TipoTPF | None = None,
    completo: bool = False,
) -> pl.DataFrame:
    """Busca taxas e preços indicativos de TPFs.

    Fonte: ANBIMA. Primeiro consulta o cache local de dados históricos; se a
    data não estiver no cache, busca diretamente na fonte da ANBIMA.

    Args:
        data: Data de referência.
        titulo: Tipo do título público federal. Aceita ``LFT``, ``NTN-B``,
            ``NTN-C``, ``LTN``, ``NTN-F`` ou ``PRE``.
        completo: Se verdadeiro, retorna os dados da ANBIMA sem cache nem filtro de colunas.

    Returns:
        DataFrame Polars com taxas e preços indicativos. Retorna DataFrame
        vazio se não houver dados para a data.

    Output Columns:
        * titulo (String): tipo do título público.
        * data_referencia (Date): data de referência dos dados.
        * codigo_selic (Int64): código do título no SELIC.
        * data_base (Date): data base ou de emissão do título.
        * data_vencimento (Date): data de vencimento do título.
        * pu (Float64): preço unitário para liquidação em D0.
        * taxa_compra (Float64): taxa de compra em D0.
        * taxa_venda (Float64): taxa de venda em D0.
        * taxa_indicativa (Float64): taxa indicativa em D0.

    Examples:
        >>> df = yd.tpf.taxas(data="06-02-2026")
    """
    data = converter_datas(data)

    if not data_referencia_valida(data):
        return pl.DataFrame()

    if completo:
        df = _buscar_dados_tpf(data)
    else:
        df = obter_dataset_cacheado("tpf")
        if not df.is_empty():
            df = df.filter(pl.col("data_referencia") == data)
        if df.is_empty():
            df = _buscar_dados_tpf(data)

    if df.is_empty():
        return pl.DataFrame()

    if not completo:
        df = df.select(col for col in COLUNAS_TAXAS_INDICATIVAS if col in df.columns)
        if titulo:
            tipos_titulo = _mapear_tipo_titulo(titulo)
            df = df.filter(pl.col("titulo").is_in(tipos_titulo))

    return df.sort("data_referencia", "titulo", "data_vencimento")

vencimentos(data, titulo)

Busca vencimentos de TPFs disponíveis nas taxas indicativas.

Fonte: ANBIMA, mesma base usada por yd.tpf.taxas.

Parameters:

Name Type Description Default
data DateLike

Data de referência.

 required
titulo TipoTPF

Tipo do título público federal. Aceita LFT, NTN-B, NTN-C, LTN, NTN-F ou PRE.

 required

Returns:

Type Description
Series

Series ordenada com os vencimentos disponíveis.

Examples:

>>> yd.tpf.vencimentos(data="22-08-2025", titulo="PRE")
shape: (18,)
Series: 'data_vencimento' [date]
[
    2025-10-01
    2026-01-01
    2026-04-01
    2026-07-01
    2026-10-01
    …
    2030-01-01
    2031-01-01
    2032-01-01
    2033-01-01
    2035-01-01
]
Source code in pyield/anbima/mercado_secundario.py 
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
def vencimentos(
    data: DateLike,
    titulo: TipoTPF,
) -> pl.Series:
    """Busca vencimentos de TPFs disponíveis nas taxas indicativas.

    Fonte: ANBIMA, mesma base usada por ``yd.tpf.taxas``.

    Args:
        data: Data de referência.
        titulo: Tipo do título público federal. Aceita ``LFT``, ``NTN-B``,
            ``NTN-C``, ``LTN``, ``NTN-F`` ou ``PRE``.

    Returns:
        Series ordenada com os vencimentos disponíveis.

    Examples:
        >>> yd.tpf.vencimentos(data="22-08-2025", titulo="PRE")
        shape: (18,)
        Series: 'data_vencimento' [date]
        [
            2025-10-01
            2026-01-01
            2026-04-01
            2026-07-01
            2026-10-01
            …
            2030-01-01
            2031-01-01
            2032-01-01
            2033-01-01
            2035-01-01
        ]
    """
    return taxas(data, titulo)["data_vencimento"].unique().sort()

leiloes

Busca resultados de leilões de TPFs.

Fonte: Tesouro Nacional. Dados disponíveis a partir de 04/01/2018. Retorna dados de quantidades, financeiros, taxas de colocação, duration e DV01 dos leilões no período informado.

Parameters:

Name Type Description Default
data DateLike | DatesLike | None

Data ou sequência de datas do leilão. Padrão é None.

 None
inicio DateLike | None

Data inicial da consulta. Padrão é None.

 None
fim DateLike | None

Data final da consulta. Padrão é None.

 None

Returns:

Type Description
DataFrame

DataFrame Polars com os dados processados dos leilões. Se data for
DataFrame

uma sequência, concatena os resultados das datas informadas. Se
DataFrame

inicio for informado, retorna os leilões a partir dessa data. Se
DataFrame

nenhum filtro temporal for informado, retorna o histórico completo.
DataFrame

Retorna DataFrame vazio se não houver dados para o período.
Output Columns
  • data_1v (Date): data de realização do leilão.
  • data_liquidacao_1v (Date): data de liquidação financeira da 1ª volta.
  • data_liquidacao_2v (Date): data de liquidação financeira da 2ª volta.
  • numero_edital (Int64): número do edital do leilão.
  • tipo_leilao (String): tipo da operação.
  • tipo_ocorrencia (String): classificação da ocorrência do leilão.
  • titulo (String): código do título público leiloado.
  • benchmark (String): descrição de referência do título.
  • data_vencimento (Date): data de vencimento do título.
  • dias_uteis (Int32): dias úteis entre liquidação e vencimento.
  • dias_corridos (Int32): dias corridos entre liquidação e vencimento.
  • duration (Float64): duration de Macaulay em anos.
  • prazo_medio (Float64): maturidade média em anos.
  • quantidade_ofertada_1v (Int64): quantidade ofertada na 1ª volta.
  • quantidade_ofertada_2v (Int64): quantidade ofertada na 2ª volta.
  • quantidade_aceita_1v (Int64): quantidade aceita na 1ª volta.
  • quantidade_aceita_2v (Int64): quantidade aceita na 2ª volta.
  • quantidade_aceita_total (Int64): quantidade aceita total.
  • quantidade_liquidada_1v (Int64): quantidade liquidada na 1ª volta.
  • quantidade_liquidada_2v (Int64): quantidade liquidada na 2ª volta.
  • financeiro_ofertado_1v (Float64): financeiro ofertado na 1ª volta.
  • financeiro_ofertado_2v (Float64): financeiro ofertado na 2ª volta.
  • financeiro_ofertado_total (Float64): financeiro ofertado total.
  • financeiro_aceito_1v (Float64): financeiro aceito na 1ª volta.
  • financeiro_aceito_2v (Float64): financeiro aceito na 2ª volta.
  • financeiro_aceito_total (Float64): financeiro aceito total.
  • quantidade_bcb (Int64): quantidade adquirida pelo Banco Central.
  • financeiro_bcb (Int64): financeiro adquirido pelo Banco Central.
  • colocacao_1v (Float64): taxa de colocação da 1ª volta.
  • colocacao_2v (Float64): taxa de colocação da 2ª volta.
  • colocacao_total (Float64): taxa de colocação total.
  • dv01_1v (Float64): DV01 da 1ª volta em reais.
  • dv01_2v (Float64): DV01 da 2ª volta em reais.
  • dv01_total (Float64): DV01 total em reais.
  • ptax (Float64): PTAX usada na conversão para dólar.
  • dv01_1v_usd (Float64): DV01 da 1ª volta em dólar.
  • dv01_2v_usd (Float64): DV01 da 2ª volta em dólar.
  • dv01_total_usd (Float64): DV01 total em dólar.
  • pu_minimo (Float64): preço unitário mínimo aceito.
  • pu_medio (Float64): preço unitário médio ponderado aceito.
  • tipo_pu_medio (String): origem do PU médio.
  • taxa_media (Float64): taxa média aceita.
  • taxa_maxima (Float64): taxa máxima aceita.
Notes

data não pode ser combinado com inicio ou fim. fim só pode ser usado junto com inicio.

Source code in pyield/tpf/leiloes.py 
352
353
354
355
356
357
358
359
360
361
362
363
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
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
def leiloes(
    *,
    data: DateLike | DatesLike | None = None,
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
) -> pl.DataFrame:
    """Busca resultados de leilões de TPFs.

    Fonte: Tesouro Nacional. Dados disponíveis a partir de 04/01/2018.
    Retorna dados de quantidades, financeiros, taxas de colocação, duration e
    DV01 dos leilões no período informado.

    Args:
        data: Data ou sequência de datas do leilão. Padrão é ``None``.
        inicio: Data inicial da consulta. Padrão é ``None``.
        fim: Data final da consulta. Padrão é ``None``.

    Returns:
        DataFrame Polars com os dados processados dos leilões. Se ``data`` for
        uma sequência, concatena os resultados das datas informadas. Se
        ``inicio`` for informado, retorna os leilões a partir dessa data. Se
        nenhum filtro temporal for informado, retorna o histórico completo.
        Retorna DataFrame vazio se não houver dados para o período.

    Output Columns:
        * data_1v (Date): data de realização do leilão.
        * data_liquidacao_1v (Date): data de liquidação financeira da 1ª volta.
        * data_liquidacao_2v (Date): data de liquidação financeira da 2ª volta.
        * numero_edital (Int64): número do edital do leilão.
        * tipo_leilao (String): tipo da operação.
        * tipo_ocorrencia (String): classificação da ocorrência do leilão.
        * titulo (String): código do título público leiloado.
        * benchmark (String): descrição de referência do título.
        * data_vencimento (Date): data de vencimento do título.
        * dias_uteis (Int32): dias úteis entre liquidação e vencimento.
        * dias_corridos (Int32): dias corridos entre liquidação e vencimento.
        * duration (Float64): duration de Macaulay em anos.
        * prazo_medio (Float64): maturidade média em anos.
        * quantidade_ofertada_1v (Int64): quantidade ofertada na 1ª volta.
        * quantidade_ofertada_2v (Int64): quantidade ofertada na 2ª volta.
        * quantidade_aceita_1v (Int64): quantidade aceita na 1ª volta.
        * quantidade_aceita_2v (Int64): quantidade aceita na 2ª volta.
        * quantidade_aceita_total (Int64): quantidade aceita total.
        * quantidade_liquidada_1v (Int64): quantidade liquidada na 1ª volta.
        * quantidade_liquidada_2v (Int64): quantidade liquidada na 2ª volta.
        * financeiro_ofertado_1v (Float64): financeiro ofertado na 1ª volta.
        * financeiro_ofertado_2v (Float64): financeiro ofertado na 2ª volta.
        * financeiro_ofertado_total (Float64): financeiro ofertado total.
        * financeiro_aceito_1v (Float64): financeiro aceito na 1ª volta.
        * financeiro_aceito_2v (Float64): financeiro aceito na 2ª volta.
        * financeiro_aceito_total (Float64): financeiro aceito total.
        * quantidade_bcb (Int64): quantidade adquirida pelo Banco Central.
        * financeiro_bcb (Int64): financeiro adquirido pelo Banco Central.
        * colocacao_1v (Float64): taxa de colocação da 1ª volta.
        * colocacao_2v (Float64): taxa de colocação da 2ª volta.
        * colocacao_total (Float64): taxa de colocação total.
        * dv01_1v (Float64): DV01 da 1ª volta em reais.
        * dv01_2v (Float64): DV01 da 2ª volta em reais.
        * dv01_total (Float64): DV01 total em reais.
        * ptax (Float64): PTAX usada na conversão para dólar.
        * dv01_1v_usd (Float64): DV01 da 1ª volta em dólar.
        * dv01_2v_usd (Float64): DV01 da 2ª volta em dólar.
        * dv01_total_usd (Float64): DV01 total em dólar.
        * pu_minimo (Float64): preço unitário mínimo aceito.
        * pu_medio (Float64): preço unitário médio ponderado aceito.
        * tipo_pu_medio (String): origem do PU médio.
        * taxa_media (Float64): taxa média aceita.
        * taxa_maxima (Float64): taxa máxima aceita.

    Notes:
        ``data`` não pode ser combinado com ``inicio`` ou ``fim``. ``fim`` só
        pode ser usado junto com ``inicio``.
    """
    if data is not None and (inicio is not None or fim is not None):
        msg = "data não pode ser combinado com inicio ou fim."
        raise ValueError(msg)
    if fim is not None and inicio is None:
        msg = "fim só pode ser usado junto com inicio."
        raise ValueError(msg)

    if data is not None:
        if any_is_empty(data):
            return pl.DataFrame()

        datas = cv.converter_datas(data)
        if not isinstance(datas, pl.Series):
            return _processar_data_unica(datas)

        if datas.null_count() > 0:
            msg = "data deve conter apenas datas válidas."
            raise ValueError(msg)

        resultados = [_processar_data_unica(data) for data in datas]
        resultados = [df for df in resultados if not df.is_empty()]
        if not resultados:
            return pl.DataFrame()
        return pl.concat(resultados)

    data_inicio = cv.converter_datas(inicio) if inicio is not None else None
    data_fim = cv.converter_datas(fim) if fim is not None else None

    if data_inicio is not None and data_fim is not None and data_inicio > data_fim:
        msg = "inicio deve ser menor ou igual a fim."
        raise ValueError(msg)

    dados_leilao = _buscar_dados_leiloes(
        ano_inicial=data_inicio.year if data_inicio is not None else None
    )
    return _processar_dados_leiloes(dados_leilao, inicio=data_inicio, fim=data_fim)