API de cotação do dólar: euro e histórico PTAX em Python

Use /api/v2/currency para consultar a cotação atual do dólar, euro e outras moedas. Use /api/v2/currency/historical quando precisar da série diária PTAX.

As duas rotas parecem intercambiáveis e não são. A cotação atual tem compra, venda, máxima, mínima e horário. O histórico tem uma observação de fechamento por dia útil, sem nada do que aconteceu no meio do caminho.

Aqui vai a integração em Python e o formato do JSON. Para estudar a série com mais profundidade, leia o histórico PTAX do dólar, euro e libra.

Cotação atual de dólar e euro

O parâmetro currency recebe pares no formato ORIGEM-DESTINO. Separe vários pares com vírgula.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/currency?currency=USD-BRL,EUR-BRL"

A resposta inclui uma lista em currency. Cada item tem estes campos:

Repare que preços e variações chegam como texto. Quando o cálculo exigir precisão, converta com Decimal. float acumula erro de arredondamento em spread e conversão.

{
  "currency": [
    {
      "fromCurrency": "USD",
      "toCurrency": "BRL",
      "name": "Dólar Americano/Real Brasileiro",
      "high": "5.343",
      "low": "5.20858",
      "bidPrice": "5.2159",
      "askPrice": "5.2189",
      "percentageChange": "-1.035958",
      "updatedAtDate": "2026-02-06 19:02:28"
    }
  ]
}

Os valores acima ilustram a estrutura. Chame o endpoint para ver a cotação disponível no momento.

Ler a cotação com Python

O exemplo busca dois pares e converte para Decimal antes de calcular o spread.

import os
from decimal import Decimal

import requests

response = requests.get(
    "https://brapi.dev/api/v2/currency",
    params={"currency": "USD-BRL,EUR-BRL"},
    headers={"Authorization": f"Bearer {os.environ['BRAPI_TOKEN']}"},
    timeout=30,
)
response.raise_for_status()

for quote in response.json()["currency"]:
    bid = Decimal(quote["bidPrice"])
    ask = Decimal(quote["askPrice"])
    spread = ask - bid

    pair = f"{quote['fromCurrency']}-{quote['toCurrency']}"
    print(pair, bid, ask, spread, quote["updatedAtDate"])

Exiba updatedAtDate ao lado do preço, sempre. A API não promete cotação em tempo real, e o horário é a única forma de o usuário saber de quando é aquele número.

Histórico diário PTAX

O endpoint histórico usa o mesmo nome de par e aceita startDate, endDate, sortOrder e limit.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/currency/historical?currency=USD-BRL,EUR-BRL&startDate=2026-01-01&endDate=2026-01-31&sortOrder=asc"

Atenção a uma pegadinha: aqui a chave é results, não currency. Cada resultado identifica o par e traz suas observações.

{
  "results": [
    {
      "pair": "USD-BRL",
      "fromCurrency": "USD",
      "toCurrency": "BRL",
      "observations": [
        { "date": "2026-01-02", "value": 5.12 },
        { "date": "2026-01-05", "value": 5.09 }
      ]
    }
  ]
}

A PTAX é diária, então fim de semana e feriado bancário simplesmente não têm ponto. Preencher com zero destrói qualquer média. Repetir o último valor é defensável, mas só quando a sua regra de negócio pedir isso de forma explícita.

import os
import pandas as pd
import requests

response = requests.get(
    "https://brapi.dev/api/v2/currency/historical",
    params={
        "currency": "USD-BRL",
        "startDate": "2026-01-01",
        "endDate": "2026-06-30",
        "sortOrder": "asc",
        "limit": 365,
    },
    headers={"Authorization": f"Bearer {os.environ['BRAPI_TOKEN']}"},
    timeout=30,
)
response.raise_for_status()

result = response.json()["results"][0]
frame = pd.DataFrame(result["observations"])
frame["date"] = pd.to_datetime(frame["date"])
frame = frame.set_index("date")

print(frame.tail())

Atual e histórico não devem compartilhar o mesmo campo

Uma tabela de cotações atuais guarda bidPrice, askPrice e updatedAtDate. Uma tabela histórica guarda pair, date e value.

Jogar os dois formatos numa coluna chamada price parece prático no primeiro dia. Seis meses depois, ninguém consegue dizer se aquele número era bid, ask ou fechamento PTAX, e a série inteira perde valor.

Para conversões entre moedas estrangeiras, veja o artigo sobre cross-rates com PTAX. Consulte também a documentação de câmbio atual e a documentação do histórico.

Descobrir pares disponíveis

Antes de aceitar um par digitado pelo usuário, valide contra /api/v2/currency/available. O filtro search pesquisa pelo código ou pela descrição.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/currency/available?search=EUR"

A resposta lista objetos com name e currency. É o valor de name que vai no parâmetro currency das outras rotas, o que soa invertido na primeira vez.

Perguntas frequentes

Como consultar a cotação do dólar em JSON?

Faça GET /api/v2/currency?currency=USD-BRL. Leia compra e venda em bidPrice e askPrice.

Como obter o dólar de uma data específica?

Use /api/v2/currency/historical com startDate e endDate. Procure a data em results[0].observations.

A PTAX é uma cotação em tempo real?

Não. A série histórica tem uma referência por dia útil. Para a cotação disponível agora, use a rota atual e confira updatedAtDate.

Crie sua chave e teste a API de cotação do dólar