Pular para conteúdo

PTAX

yd.ptax e yd.ptax_serie consultam a cotação de venda do dólar no Banco Central, em R\(/US\). Os valores são convertidos diretamente do texto da fonte para Decimal, com quatro casas decimais.

A consulta escalar retorna Decimal("NaN") se não houver cotação. A série retorna um DataFrame com data (pl.Date) e cotacao (pl.Decimal(18, 4)), preservando o esquema quando vazio.

import pyield as yd

cotacao = yd.ptax("22-04-2025")
historico = yd.ptax_serie("22-04-2025", "25-04-2025")

Veja as notas de migração da 0.62.0 para converter explicitamente os resultados para ponto flutuante.

Cotação PTAX de venda para uma data específica.

Retorna a PTAX de venda, taxa de câmbio oficial do dólar no Brasil, via SGS do Banco Central (série 1).

Parameters:

Name Type Description Default
data DateLike

Data desejada.

required

Returns:

Name Type Description
Decimal Decimal

Cotação PTAX de venda em R\(/US\) com quatro casas decimais, ou

Decimal

Decimal('NaN') se não houver cotação (feriado, fim de semana ou

Decimal

data futura).

Examples:

>>> import pyield as yd
>>> yd.ptax("22-04-2025")
Decimal('5.7496')
>>> yd.ptax("20-04-2025")
Decimal('NaN')
Source code in pyield/bc/sgs.py
def ptax(data: DateLike) -> Decimal:
    """Cotação PTAX de venda para uma data específica.

    Retorna a PTAX de venda, taxa de câmbio oficial do dólar no
    Brasil, via SGS do Banco Central (série 1).

    Args:
        data: Data desejada.

    Returns:
        Decimal: Cotação PTAX de venda em R$/US$ com quatro casas decimais, ou
        ``Decimal('NaN')`` se não houver cotação (feriado, fim de semana ou
        data futura).

    Examples:
        >>> import pyield as yd
        >>> yd.ptax("22-04-2025")
        Decimal('5.7496')

        >>> yd.ptax("20-04-2025")
        Decimal('NaN')
    """
    if any_is_empty(data):
        return Decimal("NaN")
    data = converter_datas(data)
    if not data_referencia_valida(data):
        return Decimal("NaN")

    return _extrair_escalar(ptax_serie(data, data), "cotacao")

Cotação PTAX de venda do dólar (série SGS 1).

Fonte: Banco Central do Brasil (BCB). Frequência diária.

A cotação retornada é a PTAX de venda, a taxa de câmbio oficial do dólar no Brasil, usada como referência para liquidação de contratos, marcação a mercado de derivativos, conversão de DV01 e índices de fundos cambiais.

Parameters:

Name Type Description Default
inicio DateLike | None

Data inicial.

None
fim DateLike | None

Data final. Se None, usa a data de hoje.

None
ultimos int | None

Número de registros mais recentes a retornar. Se informado, tem prioridade sobre inicio e fim.

None

Returns:

Type Description
DataFrame

DataFrame com colunas data e cotacao, ou DataFrame vazio

DataFrame

se não houver dados.

Output Columns
  • data (Date): data da cotação.
  • cotacao (pl.Decimal(18, 4)): cotação PTAX de venda em R\(/US\).
Notes

Disponível desde 28.11.1984. Refere-se às taxas administradas até março de 1990 e às taxas livres a partir de então (Resolução 1690, de 18.3.1990). A partir de março de 1992, essa taxa recebeu a denominação PTAX. Desde 1 de julho de 2011 (Circular 3506), a PTAX corresponde à média aritmética das taxas obtidas em quatro consultas diárias aos dealers de câmbio. Os valores são convertidos diretamente do texto para Decimal, sem passagem por float, com quatro casas decimais.

Examples:

>>> import pyield as yd
>>> yd.ptax_serie("20-04-2025", "25-04-2025")
shape: (4, 2)
┌────────────┬───────────────┐
│ data       ┆ cotacao       │
│ ---        ┆ ---           │
│ date       ┆ decimal[18,4] │
╞════════════╪═══════════════╡
│ 2025-04-22 ┆ 5.7496        │
│ 2025-04-23 ┆ 5.6880        │
│ 2025-04-24 ┆ 5.6738        │
│ 2025-04-25 ┆ 5.6846        │
└────────────┴───────────────┘
Source code in pyield/bc/sgs.py
def ptax_serie(
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
    *,
    ultimos: int | None = None,
) -> pl.DataFrame:
    """Cotação PTAX de venda do dólar (série SGS 1).

    Fonte: Banco Central do Brasil (BCB). Frequência diária.

    A cotação retornada é a PTAX de **venda**, a taxa de câmbio
    oficial do dólar no Brasil, usada como referência para
    liquidação de contratos, marcação a mercado de derivativos,
    conversão de DV01 e índices de fundos cambiais.

    Args:
        inicio: Data inicial.
        fim: Data final. Se ``None``, usa a data de hoje.
        ultimos: Número de registros mais recentes a retornar. Se informado,
            tem prioridade sobre ``inicio`` e ``fim``.

    Returns:
        DataFrame com colunas data e cotacao, ou DataFrame vazio
        se não houver dados.

    Output Columns:
        * data (Date): data da cotação.
        * cotacao (pl.Decimal(18, 4)): cotação PTAX de venda em R$/US$.

    Notes:
        Disponível desde 28.11.1984. Refere-se às taxas administradas até
        março de 1990 e às taxas livres a partir de então (Resolução 1690,
        de 18.3.1990). A partir de março de 1992, essa taxa recebeu a
        denominação PTAX. Desde 1 de julho de 2011 (Circular 3506), a PTAX
        corresponde à média aritmética das taxas obtidas em quatro consultas
        diárias aos dealers de câmbio.
        Os valores são convertidos diretamente do texto para Decimal, sem
        passagem por float, com quatro casas decimais.

    Examples:
        >>> import pyield as yd
        >>> yd.ptax_serie("20-04-2025", "25-04-2025")
        shape: (4, 2)
        ┌────────────┬───────────────┐
        │ data       ┆ cotacao       │
        │ ---        ┆ ---           │
        │ date       ┆ decimal[18,4] │
        ╞════════════╪═══════════════╡
        │ 2025-04-22 ┆ 5.7496        │
        │ 2025-04-23 ┆ 5.6880        │
        │ 2025-04-24 ┆ 5.6738        │
        │ 2025-04-25 ┆ 5.6846        │
        └────────────┴───────────────┘
    """
    return _buscar_serie(SerieSGS.PTAX_VENDA, inicio, fim, ultimos).select(
        "data",
        cotacao=pl.col("valor").cast(_TIPO_PTAX),
    )