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, dealers, 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.

Taxas indicativas

Use yd.tpf.taxas(...) para consultar uma data e yd.tpf.taxas_historicas(...) para consultar um período ou todo o histórico disponível. As duas funções retornam o mesmo conjunto estável de colunas.

import pyield as yd

taxas_dia = yd.tpf.taxas("23-08-2024", titulo="PRE")
taxas_periodo = yd.tpf.taxas_historicas(
    inicio="01-08-2024",
    fim="31-08-2024",
    titulo="PRE",
)

Convenções de escala e precisão

A tabela resume as regras adotadas pela PYield na precificação de títulos públicos federais. LTN, NTN-F, NTN-B, NTN-C e LFT seguem a metodologia da STN para títulos ofertados em leilões primários. A NTN-B Principal e a NTN-B1, vendidas exclusivamente pelo Tesouro Direto, seguem as regras próprias desse programa.

Variáveis LTN NTN-F NTN-B NTN-B Principal NTN-B1 NTN-C LFT
Taxa de retorno T8 / I8 T8 / I8 T8 / I8 A4 I T8 / I8 T8 / I8
Juros semestrais (a.a.) -- A5 A8 -- -- A8 --
Fluxo de pagamentos descontados -- A9 A12 -- A12 A12 --
Cotação (base 1) -- -- T6 T6 T6 T6 T6
Valor nominal atualizado (VNA) -- -- T6 / I6 I6 I6 T6 / I6 T6 / I6
Valor nominal atualizado (VNA, projeções) -- -- T6 -- -- T6 T6
Fator acumulado da taxa Selic -- -- -- -- -- -- A16
Projeções -- -- A4 -- -- A4 --
Fator pro rata (projeções) -- -- T14 -- -- T14 --
Variação do mês oficial -- -- T16 -- -- T16 --
Exponencial de dias T14 T14 T14 T14 T14 T14 T14
Preço unitário (PU) T6 / I6 T6 / I6 T6 T6 T6 T6 T6
Valor financeiro T2 T2 T2 T2 T2 T2 T2

Na tabela, T significa truncado, A, arredondado, e I, informado. Na NTN-B1, T6 descreve a função cotacao. A função cotacao_curva_zero arredonda cada fluxo em A12, mas não trunca a soma final, pois ela é usada como alvo da calibração da taxa equivalente.

Na metodologia da STN para os leilões primários, taxas, projeções, cupons e cotações são apresentados na escala percentual ou em base 100. A PYield recebe taxas e representa cotações como fatores decimais em base 1. Por isso, as regras correspondentes são deslocadas em duas casas: T6 para a taxa percentual torna-se T8 para a taxa decimal, T4 torna-se T6 para a cotação, A6 torna-se A8 e A10 torna-se A12.

Por exemplo, a cotação 99,3651 apresentada pela STN corresponde ao fator 0,993651 retornado pela PYield. As duas representações preservam o mesmo valor e a mesma precisão normativa:

pu = vna * cotacao

As regras usadas para LTN, NTN-F, NTN-B, NTN-C e LFT estão na metodologia da STN para os títulos ofertados em leilões primários.

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/titulos/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
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  │
        └─────────────────┴────────────┴───────────┘
    """
    from pyield.tpf.titulos import ntnf  # noqa: PLC0415

    df_ltn = utils.obter_tpf(data, "LTN").select(
        "data_vencimento", "taxa_indicativa"
    )
    df_ntnf = utils.obter_tpf(data, "NTN-F").select(
        "data_vencimento", "taxa_indicativa"
    )

    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,
            }
        )

    if df_ltn.is_empty():
        raise ValueError(
            "Não é possível construir a curva PRE sem taxas de LTN para bootstrap"
        )

    if df_ntnf.is_empty():
        df = _processar_ltn_adicionais(data, df_ltn)
    else:
        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,
        )

        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():
            ltn_subset = _processar_ltn_adicionais(data, ltn_not_in_ntnf)
            df = pl.concat([df_spots, ltn_subset])
        else:
            df = df_spots

    _validar_resultado_final(df)
    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)

premios_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.premios_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/titulos/_utils.py 
 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
114
115
116
117
118
119
120
121
122
123
124
def premios_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.premios_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()
    df = adicionar_taxa_di(df, data)
    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

taxas(data, titulo=None)

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

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/tpf/_taxas.py 
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
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
def taxas(
    data: DateLike,
    titulo: TipoTPF | None = None,
) -> 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``.

    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()

    try:
        df = _obter_historico()
    except (requests.exceptions.RequestException, pl.exceptions.PolarsError):
        df = pl.DataFrame()
    if not df.is_empty():
        df = df.filter(pl.col("data_referencia") == data)
    if df.is_empty():
        df = _anbima_taxas.buscar(data)

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

    df = df.select(col for col in _COLUNAS_SAIDA 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")

taxas_historicas(inicio=None, fim=None, titulo=None)

Consulta o histórico de taxas e preços indicativos de TPFs.

Fonte: ANBIMA, em painel histórico publicado pela PYield. Os filtros de período são inclusivos. Sem argumentos, retorna todo o histórico disponível.

Parameters:

Name Type Description Default
inicio DateLike | None

Data inicial do período. Se omitida, não limita o início.

 None
fim DateLike | None

Data final do período. Se omitida, não limita o fim.

 None
titulo TipoTPF | None

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

 None

Returns:

Type Description
DataFrame

DataFrame Polars com o histórico de taxas e preços indicativos. Retorna
DataFrame

DataFrame vazio se não houver dados para os filtros informados.
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.

Raises:

Type Description
ValueError

Se inicio for posterior a fim.

Examples:

>>> df = yd.tpf.taxas_historicas(
...     inicio="01-01-2025", fim="31-01-2025", titulo="PRE"
... )
Source code in pyield/tpf/_taxas.py 
 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
114
115
116
def taxas_historicas(
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
    titulo: TipoTPF | None = None,
) -> pl.DataFrame:
    """Consulta o histórico de taxas e preços indicativos de TPFs.

    Fonte: ANBIMA, em painel histórico publicado pela PYield. Os filtros de
    período são inclusivos. Sem argumentos, retorna todo o histórico disponível.

    Args:
        inicio: Data inicial do período. Se omitida, não limita o início.
        fim: Data final do período. Se omitida, não limita o fim.
        titulo: Tipo do título público federal. Aceita ``LFT``, ``NTN-B``,
            ``NTN-C``, ``LTN``, ``NTN-F`` ou ``PRE``.

    Returns:
        DataFrame Polars com o histórico de taxas e preços indicativos. Retorna
        DataFrame vazio se não houver dados para os filtros informados.

    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.

    Raises:
        ValueError: Se ``inicio`` for posterior a ``fim``.

    Examples:
        >>> df = yd.tpf.taxas_historicas(
        ...     inicio="01-01-2025", fim="31-01-2025", titulo="PRE"
        ... )
    """
    data_inicio = converter_datas(inicio) if inicio is not None else None
    data_fim = 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)

    df = _obter_historico()
    if df.is_empty():
        return df

    if data_inicio is not None:
        df = df.filter(pl.col("data_referencia") >= data_inicio)
    if data_fim is not None:
        df = df.filter(pl.col("data_referencia") <= data_fim)
    if titulo:
        tipos_titulo = _mapear_tipo_titulo(titulo)
        df = df.filter(pl.col("titulo").is_in(tipos_titulo))

    return df.select(_COLUNAS_SAIDA).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/tpf/_taxas.py 
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
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()

Acesso técnico à fonte ANBIMA

O módulo pyield.anbima.taxas permite baixar ou ler o arquivo da ANBIMA com todas as colunas processadas da fonte. Essa camada é indicada para integração com a fonte; para análises de TPF, prefira a visão estável de yd.tpf.

Taxas de Títulos Públicos Federais (TPF) da ANBIMA.

Fonte

https://www.anbima.com.br/pt_br/informar/taxas-de-titulos-publicos.htm

Exemplo de URL

https://www.anbima.com.br/informacoes/merc-sec/arqs/ms240614.txt

Exemplo de dado bruto (CSV separado por @, encoding latin1): ANBIMA - Associação Brasileira das Entidades dos Mercados Financeiro e de Capitais

Titulo@Data Referencia@Codigo SELIC@Data Base/Emissao@Data Vencimento@Tx. Compra@Tx. Venda@Tx. Indicativas@PU@Desvio padrao@Interv. Ind. Inf. (D0)@Interv. Ind. Sup. (D0)@Interv. Ind. Inf. (D+1)@Interv. Ind. Sup. (D+1)@Criterio
LTN@20250924@100000@20230707@20251001@14,9483@14,9263@14,9375@997,241543@0,00433039162894@14,7341@15,2612@14,7316@15,2689@Calculado
LTN@20250924@100000@20200206@20260101@14,7741@14,7485@14,7616@963,001853@0,00729826731971@14,7008@14,9986@14,7021@14,9975@Calculado

baixar_arquivo(data)

Baixa o arquivo bruto de taxas de TPF publicado pela ANBIMA.

Parameters:

Name Type Description Default
data DateLike

Data de referência do arquivo.

 required

Returns:

Type Description
bytes

Bytes do arquivo publicado pela ANBIMA, sem decodificação ou parsing.

Raises:

Type Description
HTTPError

Se o arquivo não estiver disponível ou a resposta HTTP indicar erro.
ValueError

Se data não for uma data escalar válida.
Source code in pyield/anbima/taxas.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def baixar_arquivo(data: DateLike) -> bytes:
    """Baixa o arquivo bruto de taxas de TPF publicado pela ANBIMA.

    Args:
        data: Data de referência do arquivo.

    Returns:
        Bytes do arquivo publicado pela ANBIMA, sem decodificação ou parsing.

    Raises:
        requests.HTTPError: Se o arquivo não estiver disponível ou a resposta
            HTTP indicar erro.
        ValueError: Se ``data`` não for uma data escalar válida.
    """
    if isinstance(data, str) and not data.strip():
        msg = "data deve ser escalar para baixar um arquivo da ANBIMA"
        raise ValueError(msg)
    data_arquivo = converter_datas(data)
    return _obter_csv(data_arquivo)

buscar(data)

Busca e processa taxas de TPF diretamente na ANBIMA.

Fonte: arquivo de taxas de títulos públicos da ANBIMA.

Parameters:

Name Type Description Default
data DateLike

Data de referência do arquivo.

 required

Returns:

Type Description
DataFrame

DataFrame com todas as colunas processadas da fonte. Retorna DataFrame
DataFrame

vazio para datas válidas sem dados disponíveis.
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.
  • taxa_compra (Float64): taxa de compra em D0.
  • taxa_venda (Float64): taxa de venda em D0.
  • taxa_indicativa (Float64): taxa indicativa em D0.
  • pu (Float64): preço unitário para liquidação em D0.
  • desvio_padrao (Float64): desvio padrão das taxas observadas.
  • taxa_intervalo_inf_d0 (Float64): limite inferior indicativo em D0.
  • taxa_intervalo_sup_d0 (Float64): limite superior indicativo em D0.
  • taxa_intervalo_inf_d1 (Float64): limite inferior indicativo em D+1.
  • taxa_intervalo_sup_d1 (Float64): limite superior indicativo em D+1.
  • criterio (String): critério usado pela ANBIMA para o título.

Raises:

Type Description
ValueError

Se data não for uma data escalar válida.
Source code in pyield/anbima/taxas.py 
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
221
222
223
def buscar(data: DateLike) -> pl.DataFrame:
    """Busca e processa taxas de TPF diretamente na ANBIMA.

    Fonte: arquivo de taxas de títulos públicos da ANBIMA.

    Args:
        data: Data de referência do arquivo.

    Returns:
        DataFrame com todas as colunas processadas da fonte. Retorna DataFrame
        vazio para datas válidas sem dados disponíveis.

    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.
        * taxa_compra (Float64): taxa de compra em D0.
        * taxa_venda (Float64): taxa de venda em D0.
        * taxa_indicativa (Float64): taxa indicativa em D0.
        * pu (Float64): preço unitário para liquidação em D0.
        * desvio_padrao (Float64): desvio padrão das taxas observadas.
        * taxa_intervalo_inf_d0 (Float64): limite inferior indicativo em D0.
        * taxa_intervalo_sup_d0 (Float64): limite superior indicativo em D0.
        * taxa_intervalo_inf_d1 (Float64): limite inferior indicativo em D+1.
        * taxa_intervalo_sup_d1 (Float64): limite superior indicativo em D+1.
        * criterio (String): critério usado pela ANBIMA para o título.

    Raises:
        ValueError: Se ``data`` não for uma data escalar válida.
    """
    data = converter_datas(data)
    if not data_referencia_valida(data):
        return pl.DataFrame()

    url_arquivo = _montar_url_arquivo(data)

    # Fail-fast: se a URL é RTM e o host não resolve, não adianta tentar
    if ANBIMA_RTM_URL in url_arquivo:
        try:
            socket.gethostbyname(ANBIMA_RTM_HOSTNAME)
        except socket.gaierror:
            data_str = data.strftime("%d/%m/%Y")
            logger.warning(
                f"Não foi possível resolver o host da RTM para {data_str}. "
                "Dados históricos exigem acesso à rede RTM."
            )
            return pl.DataFrame()

    csv_bytes = _obter_csv(data)
    if not csv_bytes.strip():
        return pl.DataFrame()

    return ler(csv_bytes)

ler(fonte)

Lê taxas de TPF da ANBIMA a partir de bytes ou arquivo local.

Fonte: arquivo de taxas de títulos públicos da ANBIMA.

Arquivos atuais .txt são lidos diretamente. Arquivos históricos .exe são tratados como ZIPs e o arquivo interno é lido.

Parameters:

Name Type Description Default
fonte bytes | _CaminhoArquivo

Bytes do arquivo bruto ou caminho do arquivo salvo localmente.

 required

Returns:

Type Description
DataFrame

DataFrame Polars com todas as colunas processadas da fonte.
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.
  • taxa_compra (Float64): taxa de compra em D0.
  • taxa_venda (Float64): taxa de venda em D0.
  • taxa_indicativa (Float64): taxa indicativa em D0.
  • pu (Float64): preço unitário para liquidação em D0.
  • desvio_padrao (Float64): desvio padrão das taxas observadas.
  • taxa_intervalo_inf_d0 (Float64): limite inferior indicativo em D0.
  • taxa_intervalo_sup_d0 (Float64): limite superior indicativo em D0.
  • taxa_intervalo_inf_d1 (Float64): limite inferior indicativo em D+1.
  • taxa_intervalo_sup_d1 (Float64): limite superior indicativo em D+1.
  • criterio (String): critério usado pela ANBIMA para o título.
Source code in pyield/anbima/taxas.py 
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
def ler(fonte: bytes | _CaminhoArquivo) -> pl.DataFrame:
    """Lê taxas de TPF da ANBIMA a partir de bytes ou arquivo local.

    Fonte: arquivo de taxas de títulos públicos da ANBIMA.

    Arquivos atuais ``.txt`` são lidos diretamente. Arquivos históricos
    ``.exe`` são tratados como ZIPs e o arquivo interno é lido.

    Args:
        fonte: Bytes do arquivo bruto ou caminho do arquivo salvo localmente.

    Returns:
        DataFrame Polars com todas as colunas processadas da fonte.

    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.
        * taxa_compra (Float64): taxa de compra em D0.
        * taxa_venda (Float64): taxa de venda em D0.
        * taxa_indicativa (Float64): taxa indicativa em D0.
        * pu (Float64): preço unitário para liquidação em D0.
        * desvio_padrao (Float64): desvio padrão das taxas observadas.
        * taxa_intervalo_inf_d0 (Float64): limite inferior indicativo em D0.
        * taxa_intervalo_sup_d0 (Float64): limite superior indicativo em D0.
        * taxa_intervalo_inf_d1 (Float64): limite inferior indicativo em D+1.
        * taxa_intervalo_sup_d1 (Float64): limite superior indicativo em D+1.
        * criterio (String): critério usado pela ANBIMA para o título.
    """
    conteudo = fonte if isinstance(fonte, bytes) else Path(fonte).read_bytes()
    if zf.is_zipfile(io.BytesIO(conteudo)):
        with zf.ZipFile(io.BytesIO(conteudo)) as arquivo_zip:
            conteudo = arquivo_zip.read(arquivo_zip.namelist()[0])
    return _processar_df(_parsear_df(conteudo))

secundario

Negociações do mercado secundário de TPFs no sistema Selic do BCB.

baixar_zip(data, extragrupo=False)

Baixa o ZIP bruto mensal de negociações secundárias de TPFs.

Fonte: Banco Central do Brasil, sistema SELIC. A fonte publica um arquivo por mês; por isso, apenas o ano e o mês de data são usados.

A função valida a estrutura mínima do ZIP antes de retornar os bytes, para evitar que pipelines de ingestão salvem bronze vazio, corrompido ou sem CSV plausível.

Parameters:

Name Type Description Default
data DateLike

Data de referência. Apenas ano e mês definem o arquivo.

 required
extragrupo bool

Se verdadeiro, baixa o arquivo extragrupo.

 False

Returns:

Type Description
bytes

Bytes validados do arquivo ZIP mensal publicado pelo BCB.

Raises:

Type Description
HTTPError

Se o arquivo não estiver disponível no BCB ou a resposta HTTP indicar erro.
ValueError

Se o conteúdo baixado não for um ZIP bruto plausível.

Examples:

>>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")
Source code in pyield/tpf/secundario/_mensal.py 
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
def baixar_zip(data: DateLike, extragrupo: bool = False) -> bytes:
    """Baixa o ZIP bruto mensal de negociações secundárias de TPFs.

    Fonte: Banco Central do Brasil, sistema SELIC. A fonte publica um arquivo
    por mês; por isso, apenas o ano e o mês de ``data`` são usados.

    A função valida a estrutura mínima do ZIP antes de retornar os bytes, para
    evitar que pipelines de ingestão salvem bronze vazio, corrompido ou sem CSV
    plausível.

    Args:
        data: Data de referência. Apenas ano e mês definem o arquivo.
        extragrupo: Se verdadeiro, baixa o arquivo extragrupo.

    Returns:
        Bytes validados do arquivo ZIP mensal publicado pelo BCB.

    Raises:
        requests.HTTPError: Se o arquivo não estiver disponível no BCB ou a
            resposta HTTP indicar erro.
        ValueError: Se o conteúdo baixado não for um ZIP bruto plausível.

    Examples:
        >>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")  # doctest: +SKIP
    """
    arquivo = nome_arquivo_mensal(data, extragrupo)
    conteudo_zip = _baixar_url_zip(f"{URL_BASE_MENSAL}/{arquivo}")
    _validar_zip(conteudo_zip, arquivo)
    return conteudo_zip

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/tpf/secundario/_intradia.py 
 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
138
139
def 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_intradia()
    df = _parsear_csv_intradia(texto_bruto)
    return _processar_df_intradia(df)

ler_zip(caminho)

Lê um ZIP mensal local do secundário de TPFs e converte para silver.

Fonte: Banco Central do Brasil, sistema SELIC. Esta função é um atalho para pipelines que salvam o bronze bruto e depois processam o arquivo local com o mesmo schema de zip_para_silver.

Parameters:

Name Type Description Default
caminho CaminhoArquivo

Caminho do arquivo ZIP bruto.

 required

Returns:

Type Description
DataFrame

DataFrame Polars com dados mensais do mercado secundário.

Examples:

>>> df = yd.tpf.secundario.ler_zip("NegT202501.ZIP")
Source code in pyield/tpf/secundario/_mensal.py 
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
def ler_zip(caminho: CaminhoArquivo) -> pl.DataFrame:
    """Lê um ZIP mensal local do secundário de TPFs e converte para silver.

    Fonte: Banco Central do Brasil, sistema SELIC. Esta função é um atalho para
    pipelines que salvam o bronze bruto e depois processam o arquivo local com o
    mesmo schema de ``zip_para_silver``.

    Args:
        caminho: Caminho do arquivo ZIP bruto.

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

    Examples:
        >>> df = yd.tpf.secundario.ler_zip("NegT202501.ZIP")  # doctest: +SKIP
    """
    return zip_para_silver(Path(caminho).read_bytes())

mensal(data, extragrupo=False)

Busca dados mensais do mercado secundário de TPFs.

Fonte: Banco Central do Brasil, sistema SELIC. Baixa o ZIP mensal de negociações secundárias, valida o bronze bruto e retorna o DataFrame ouro. Apenas o ano e o mês de data são usados para identificar o arquivo.

Parameters:

Name Type Description Default
data DateLike

Data de referência. Apenas ano e mês definem o arquivo.

 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.
  • 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.
  • financeiro (Float64): valor financeiro negociado.
Notes

Esta é a camada ouro mensal: retorna o schema de zip_para_silver acrescido de financeiro = quantidade * pu_medio.

Examples:

>>> df = yd.tpf.secundario.mensal("07-01-2025", extragrupo=True)
Source code in pyield/tpf/secundario/_mensal.py 
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
def 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 ZIP mensal de
    negociações secundárias, valida o bronze bruto e retorna o DataFrame ouro.
    Apenas o ano e o mês de ``data`` são usados para identificar o arquivo.

    Args:
        data: Data de referência. Apenas ano e mês definem o arquivo.
        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.
        * 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.
        * financeiro (Float64): valor financeiro negociado.

    Notes:
        Esta é a camada ouro mensal: retorna o schema de ``zip_para_silver``
        acrescido de ``financeiro = quantidade * pu_medio``.

    Examples:
        >>> df = yd.tpf.secundario.mensal("07-01-2025", extragrupo=True)
    """
    if any_is_empty(data):
        return pl.DataFrame()

    data_alvo = _data_mensal(data)
    hoje = relogio.hoje()
    if (data_alvo.year, data_alvo.month) > (hoje.year, hoje.month):
        return pl.DataFrame()

    return zip_para_silver(baixar_zip(data_alvo, extragrupo)).with_columns(
        financeiro=(pl.col("quantidade") * pl.col("pu_medio")).round(2),
    )

nome_arquivo_mensal(data, extragrupo=False)

Retorna o nome do arquivo ZIP mensal do secundário no BCB/SELIC.

Parameters:

Name Type Description Default
data DateLike

Data de referência. Apenas ano e mês definem o arquivo.

 required
extragrupo bool

Se verdadeiro, retorna o nome do arquivo extragrupo.

 False

Returns:

Type Description
str

Nome do arquivo ZIP mensal publicado pelo BCB.

Examples:

>>> yd.tpf.secundario.nome_arquivo_mensal("07-06-2026")
'NegT202606.ZIP'
>>> yd.tpf.secundario.nome_arquivo_mensal("07-01-2025", extragrupo=True)
'NegE202501.ZIP'
Source code in pyield/tpf/secundario/_mensal.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def nome_arquivo_mensal(data: DateLike, extragrupo: bool = False) -> str:
    """Retorna o nome do arquivo ZIP mensal do secundário no BCB/SELIC.

    Args:
        data: Data de referência. Apenas ano e mês definem o arquivo.
        extragrupo: Se verdadeiro, retorna o nome do arquivo extragrupo.

    Returns:
        Nome do arquivo ZIP mensal publicado pelo BCB.

    Examples:
        >>> yd.tpf.secundario.nome_arquivo_mensal("07-06-2026")
        'NegT202606.ZIP'
        >>> yd.tpf.secundario.nome_arquivo_mensal("07-01-2025", extragrupo=True)
        'NegE202501.ZIP'
    """
    data_alvo = _data_mensal(data)
    return f"Neg{_tipo_arquivo(extragrupo)}{data_alvo:%Y%m}.ZIP"

zip_para_silver(conteudo_zip)

Converte o ZIP mensal bruto do secundário de TPFs em silver.

Fonte: Banco Central do Brasil, sistema SELIC. Esta função representa a etapa bronze -> silver: extrai o CSV interno, limpa os campos, converte tipos e retorna o schema Polars canônico usado pela PYield. Ela não faz enriquecimento para camada ouro.

Parameters:

Name Type Description Default
conteudo_zip bytes

Bytes do arquivo ZIP bruto mensal.

 required

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.
  • 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.
Notes

O schema silver é estável para concatenação entre meses. Em layouts antigos da fonte que não trazem corretagem, operacoes_corretagem e quantidade_corretagem são retornadas como nulas.

Examples:

>>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")
>>> df = yd.tpf.secundario.zip_para_silver(conteudo)
Source code in pyield/tpf/secundario/_mensal.py 
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
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
def zip_para_silver(conteudo_zip: bytes) -> pl.DataFrame:
    """Converte o ZIP mensal bruto do secundário de TPFs em silver.

    Fonte: Banco Central do Brasil, sistema SELIC. Esta função representa a
    etapa bronze -> silver: extrai o CSV interno, limpa os campos, converte
    tipos e retorna o schema Polars canônico usado pela PYield. Ela não faz
    enriquecimento para camada ouro.

    Args:
        conteudo_zip: Bytes do arquivo ZIP bruto mensal.

    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.
        * 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.

    Notes:
        O schema silver é estável para concatenação entre meses. Em layouts
        antigos da fonte que não trazem corretagem, ``operacoes_corretagem`` e
        ``quantidade_corretagem`` são retornadas como nulas.

    Examples:
        >>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")  # doctest: +SKIP
        >>> df = yd.tpf.secundario.zip_para_silver(conteudo)  # doctest: +SKIP
    """
    conteudo_csv = _extrair_csv_zip(conteudo_zip)
    return _processar_df_mensal(_parsear_csv_mensal(conteudo_csv))

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)

dealers

Busca os dealers do Tesouro Nacional vigentes em uma data.

Dealers são instituições financeiras credenciadas pelo Tesouro Nacional para atuar nas emissões primárias e no mercado secundário de títulos públicos federais. A composição é revista periodicamente.

Fonte: API de Leilões da Dívida Pública do Tesouro Nacional.

Parameters:

Name Type Description Default
data DateLike | None

Data de referência do credenciamento. Se None, usa a data atual no Brasil.

 None

Returns:

Type Description
DataFrame

DataFrame Polars com as instituições cujo período de credenciamento
DataFrame

contém a data informada. Retorna DataFrame vazio, com esquema estável,
DataFrame

se a fonte não possuir registros para a data.
Output Columns
  • inicio_periodo (Date): início do período de credenciamento.
  • fim_periodo (Date): fim do período de credenciamento.
  • cnpj (String): CNPJ da instituição credenciada.
  • instituicao (String): nome da instituição credenciada como dealer.
Notes

A função preserva os nomes e períodos publicados pela fonte. O endpoint não informa o tipo da instituição, o conglomerado financeiro nem os objetos de negociação escolhidos pelo dealer.

Examples:

>>> df = yd.tpf.dealers("15-03-2026")
>>> df.is_empty() or df["inicio_periodo"].unique().to_list()
[datetime.date(2026, 2, 10)]
Source code in pyield/tpf/dealers.py 
 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
def dealers(data: DateLike | None = None) -> pl.DataFrame:
    """Busca os dealers do Tesouro Nacional vigentes em uma data.

    Dealers são instituições financeiras credenciadas pelo Tesouro Nacional
    para atuar nas emissões primárias e no mercado secundário de títulos
    públicos federais. A composição é revista periodicamente.

    Fonte: API de Leilões da Dívida Pública do Tesouro Nacional.

    Args:
        data: Data de referência do credenciamento. Se ``None``, usa a data
            atual no Brasil.

    Returns:
        DataFrame Polars com as instituições cujo período de credenciamento
        contém a data informada. Retorna DataFrame vazio, com esquema estável,
        se a fonte não possuir registros para a data.

    Output Columns:
        * inicio_periodo (Date): início do período de credenciamento.
        * fim_periodo (Date): fim do período de credenciamento.
        * cnpj (String): CNPJ da instituição credenciada.
        * instituicao (String): nome da instituição credenciada como dealer.

    Notes:
        A função preserva os nomes e períodos publicados pela fonte. O endpoint
        não informa o tipo da instituição, o conglomerado financeiro nem os
        objetos de negociação escolhidos pelo dealer.

    Examples:
        >>> df = yd.tpf.dealers("15-03-2026")
        >>> df.is_empty() or df["inicio_periodo"].unique().to_list()
        [datetime.date(2026, 2, 10)]
    """
    if isinstance(data, str) and not data.strip():
        return _df_vazio()
    data_referencia = relogio.hoje() if data is None else cv.converter_datas(data)

    df = _parsear_dealers(_buscar_dealers())
    if df.is_empty():
        return _df_vazio()

    return _processar_dealers(df).filter(
        pl.lit(data_referencia).is_between("inicio_periodo", "fim_periodo")
    )