Formatos de dados e unidades

Duas direções para cada cotação

Para cada símbolo solicitado, rates contém dois números. Para o ouro (XAU) com base USD:

• USDXAU: o preço de uma onça troy de ouro em dólares americanos, como 3997.89. Este é o número a ser exibido para as pessoas.
• XAU: o inverso, onças troy de ouro por um dólar americano, como 0.0002501319446. Este formato é mantido por compatibilidade com APIs no estilo forex.

As moedas seguem a mesma regra. Com base USD, USDEUR é o preço de um euro em dólares e EUR é a quantidade de euros por dólar.

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "EUR": 0.8589589418,
    "USDEUR": 1.1642
  }
}

Escolhendo uma moeda base

base define a moeda de todos os preços da resposta. O padrão é USD, e qualquer símbolo suportado é aceito: EUR, GBP, JPY ou até BTC ou XAU, se você quiser avaliar as coisas em bitcoin ou em ouro. As taxas cruzadas são calculadas a partir do mesmo snapshot, então são sempre consistentes entre si.

Esta requisição retorna EURXAU, o preço do ouro em euros por onça troy:

GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR&currencies=XAU,XAG

Unidades de massa

Os preços dos metais são por onça troy (31,1035 g), a menos que você passe unit. Valores suportados:

• troy_oz (padrão), gram, kilogram, ounce (avoirdupois, 28,35 g), pound, metric_ton e short_ton

Formas curtas como g, kg, lb e tonne também são aceitas. Observe que oz significa a onça avoirdupois. Use troy_oz, ou omita unit, para a onça troy, a unidade em que os metais preciosos de investimento são cotados.

unit se aplica apenas aos metais preciosos e industriais. A energia continua por barril, MMBtu ou galão, e moedas e cripto não são afetadas. Quando uma unidade diferente da padrão é usada, a resposta inclui um campo unit. Para GET /api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram:

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "EUR",
  "unit": "gram",
  "rates": {
    "XAU": 0.009057444725,
    "EURXAU": 110.4064149,
    "XAG": 0.6713138244,
    "EURXAG": 1.489616277
  }
}

Metais industriais e energia

Os metais industriais (XCU cobre, ALU alumínio, ZNC zinco e HRC bobina de aço laminada a quente) são cotados por onça troy por padrão, como todos os outros metais, para que todos os metais possam ser comparados diretamente. Para obter a unidade em que cada mercado negocia, passe unit=pound para o cobre, unit=metric_ton para o alumínio e o zinco, e unit=short_ton para o aço.

Os preços de energia são por unidade de contrato: WTI e BRENT por barril, NATURALGAS por MMBtu, e GASOLINE e HEATINGOIL por galão.

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XCU&unit=pound

Símbolos suportados

• Metais preciosos: XAU ouro, XAG prata, XPT platina, XPD paládio
• Metais industriais: XCU cobre, ALU alumínio, ZNC zinco, HRC aço
• Energia: WTI, BRENT, NATURALGAS, GASOLINE, HEATINGOIL
• Moedas: cerca de 55 moedas ISO 4217, incluindo USD, EUR, GBP, JPY, CHF, CAD, AUD, CNY e INR
• Cripto: BTC, ETH, SOL, XRP, BNB, ADA, DOGE, DOT, LINK, LTC, TRX, USDT, USDC

A lista completa e atualizada está na página de símbolos e também pode ser obtida em /api/v1/symbols.

Preços bid e ask

A partir do plano Standard, adicione -BID ou -ASK a um símbolo em currencies para receber os preços de compra (bid) e de venda (ask) ao lado do preço médio. Eles estão disponíveis para os símbolos cotados a partir de feeds interbancários, que são os metais preciosos e as principais moedas. Para currencies=XAU,XAU-BID,XAU-ASK:

"rates": {
  "XAU": 0.0002501319446,
  "USDXAU": 3997.89,
  "XAU-BID": 0.0002501488386,
  "USDXAU-BID": 3997.62,
  "XAU-ASK": 0.0002501150529,
  "USDXAU-ASK": 3998.16
}

Preços do ouro por quilate

/carat retorna os preços do ouro nos teores usados em joalheria, em que o teor é quilate ÷ 24, em qualquer moeda e unidade. Está disponível nos planos pagos. Para GET /api/v1/carat?carat=all&unit=gram (resumido):

{
  "success": true,
  "carat": "all",
  "date": "2026-10-23",
  "base": "USD",
  "timestamp": 1792765800,
  "rates": {
    "XAU24K": { "price": 128.53515, "unit": "gram", "carat": "24", "purity": 1 },
    "XAU22K": { "price": 117.82389, "unit": "gram", "carat": "22", "purity": 0.916667 },
    "XAU18K": { "price": 96.401361, "unit": "gram", "carat": "18", "purity": 0.75 },
    "XAU14K": { "price": 74.978836, "unit": "gram", "carat": "14", "purity": 0.583333 }
  }
}

Timestamps e datas

timestamp é o horário Unix em segundos (UTC) dos preços retornados. date é o mesmo dia no formato YYYY-MM-DD em UTC. As respostas históricas são datadas às 00:00 UTC do dia solicitado e contêm os preços de fechamento desse dia.

const date = new Date(data.timestamp * 1000);
console.log(date.toISOString()); // 2026-10-23T14:30:00.000Z

Precisão

As cotações são números JSON com até 10 dígitos significativos, o que é suficiente para cotações inversas como 0.0002501319446. Arredonde apenas ao exibir um valor, não antes de fazer cálculos com ele.

Horários de mercado e fins de semana

Os metais à vista e as moedas são negociados 24 horas por dia nos dias úteis. Os mercados fecham na sexta-feira às 17:00 no horário de Nova York e reabrem no domingo às 17:00. Durante o fim de semana, os preços ficam congelados na última cotação e a API continua retornando o preço de fechamento de sexta-feira (as páginas dos símbolos mostram “Mercado fechado”).

As criptomoedas são negociadas 24 horas por dia, 7 dias por semana, e continuam sendo atualizadas nos fins de semana. Os metais industriais e a energia seguem os horários de negociação de suas bolsas de futuros.