Endpoints disponíveis

URL base e parâmetros comuns

Todos os endpoints são requisições GET sob https://metalapi.com/api/v1 e exigem uma chave de API (veja Autenticação). A maioria deles aceita os mesmos parâmetros opcionais:

• base: a moeda em que os preços são expressos. O padrão é USD; qualquer símbolo suportado funciona.
• currencies, ou seu alias symbols: uma lista de símbolos separados por vírgula a serem retornados, como XAU,XAG,EUR. Omita-o para receber todos os símbolos.
• unit: a unidade de massa dos preços dos metais. Um destes: troy_oz (padrão), gram, kilogram, ounce, pound, metric_ton ou short_ton.

As datas usam o formato YYYY-MM-DD e são interpretadas em UTC.

Cotações mais recentes: /latest

Preços atuais no intervalo de atualização do seu plano, de diário no Free a cada 5 segundos no Enterprise. A partir do plano Standard, adicione símbolos como XAU-BID e XAU-ASK a currencies para receber os preços de compra (bid) e de venda (ask).

GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY&base=USD&currencies=XAU,XAG,EUR

Cotações históricas: /{date}

Preços de fechamento de um dia passado. Três formas são aceitas: a data como caminho, /historical?date= ou /yesterday.

GET /api/v1/2026-10-01?api_key=YOUR_API_KEY&currencies=XAU,XAG
GET /api/v1/historical?date=2026-10-01&api_key=YOUR_API_KEY&currencies=XAU,XAG
GET /api/v1/yesterday?api_key=YOUR_API_KEY&currencies=XAU,XAG

Conversão: /convert

Converte amount de from para to, por exemplo dólares em onças de ouro ou prata em euros. Adicione date para converter a um preço de fechamento histórico e unit para converter gramas ou quilogramas de um metal.

GET /api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000

# 500 gramas de prata em euros no fechamento de 1º de outubro de 2026
GET /api/v1/convert?api_key=YOUR_API_KEY&from=XAG&to=EUR&amount=500&unit=gram&date=2026-10-01

Período: /timeframe

Preços de fechamento diários para cada dia entre start_date e end_date. Uma requisição pode abranger até 30 dias no plano Free e 365 dias nos planos pagos. Intervalos maiores retornam o erro 207. /timeseries é um alias mantido por compatibilidade.

GET /api/v1/timeframe?api_key=YOUR_API_KEY&start_date=2026-09-01&end_date=2026-09-30&currencies=XAU

Variação: /change

A cotação inicial, a cotação final, a variação absoluta e a variação percentual entre duas datas para cada símbolo. Útil para exibições como “o ouro subiu 3,6% este mês”. Os limites de intervalo são os mesmos de /timeframe.

GET /api/v1/change?api_key=YOUR_API_KEY&start_date=2026-09-30&end_date=2026-10-23&currencies=XAU,XAG

OHLC: /ohlc

Abertura, máxima, mínima e fechamento de um único dia. Omita date, ou passe latest, para obter a barra de hoje até o momento.

GET /api/v1/ohlc?api_key=YOUR_API_KEY&date=2026-10-22&currencies=XAU,XAG

Ouro por quilate: /carat

Preços do ouro nos teores usados em joalheria, de 24K a 8K, em qualquer moeda e unidade. Passe carat=24 (o padrão), um único quilate como 18, ou carat=all. Os quilates suportados são 24, 23, 22, 21, 20, 18, 16, 14, 12, 10, 9 e 8. Adicione date para obter preços históricos por quilate.

Este endpoint está disponível nos planos pagos. Chaves do plano Free recebem o erro 106.

GET /api/v1/carat?api_key=YOUR_API_KEY&carat=all&base=EUR&unit=gram

Símbolos: /symbols

A lista de símbolos suportados e seus nomes. Adicione details=1 para incluir a categoria e a unidade de cada símbolo. Este endpoint não conta para a sua cota mensal.

GET /api/v1/symbols?api_key=YOUR_API_KEY&details=1

Uso: /usage

Requisições usadas e restantes no mês de faturamento atual. Também é gratuito, então você pode chamá-lo a partir do seu monitoramento sem gastar cota.

GET /api/v1/usage?api_key=YOUR_API_KEY

Stream em tempo real: /stream

Um stream de Server-Sent Events que envia as atualizações de preço assim que elas acontecem, para que você não precise fazer polling de /latest. Disponível a partir do plano Pro. A documentação de streaming descreve o formato dos eventos.

curl -N "https://metalapi.com/api/v1/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"