API de preços do ouro: o guia completo para desenvolvedores

O que uma API de preços do ouro oferece

Uma API de preços do ouro retorna o preço atual e o histórico do ouro como dados estruturados, geralmente JSON via HTTPS, para que o seu software possa usá-los sem fazer scraping de páginas web nem copiar números à mão. Na MetalAPI, o ouro tem o símbolo XAU, o código ISO 4217 para uma onça troy de ouro. O seu preço ao vivo é o preço à vista: o ponto médio entre as cotações interbancárias de compra (bid) e de venda (ask).

A maioria das integrações não é de sistemas de trading. Os usos típicos são estes:

• Lojas online e joalherias que reprecificam produtos de ouro conforme o mercado se move.
• Calculadoras de ouro usado, joias por quilate ou prêmios sobre barras e moedas.
• Acompanhamentos de carteira e apps de finanças pessoais que avaliam posições na moeda local.
• Sistemas contábeis e ERPs que reavaliam o estoque por um preço de fechamento diário.
• Painéis, newsletters e relatórios internos que precisam de um gráfico do último ano.

A mesma API cobre prata (XAG), platina (XPT) e paládio (XPD), quatro metais industriais, cinco contratos de energia, 57 moedas e 13 criptomoedas: 83 símbolos no total, todos listados na página de símbolos. Este guia se concentra no ouro, mas tudo o que está nele vale também para os outros símbolos.

Obtenha uma chave de API

Crie uma conta grátis. O plano Free não exige cartão de crédito e inclui 100 requisições por mês com atualização diária dos preços, o suficiente para desenvolver e testar uma integração. Os planos pagos acrescentam preços mais recentes, mais requisições e endpoints extras; a tabela de planos mais abaixo os resume.

No painel, abra API keys e crie uma chave. As chaves começam com mk_live_. A chave completa é exibida uma única vez, porque armazenamos apenas um hash dela, então coloque-a imediatamente em uma variável de ambiente ou em um gerenciador de segredos:

export METALAPI_KEY="mk_live_your_key_here"

A API aceita a chave de três formas equivalentes: um parâmetro de consulta api_key, um cabeçalho Authorization: Bearer ou um cabeçalho X-API-Key. Em produção, prefira um cabeçalho, porque URLs completas costumam acabar em logs de acesso, proxies e ferramentas de rastreamento de erros. O guia de autenticação também explica as chaves restritas por domínio para chamadas a partir do navegador.

# 1. Parâmetro de consulta
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

# 2. Cabeçalho Authorization
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "Authorization: Bearer $METALAPI_KEY"

# 3. Cabeçalho X-API-Key
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

Sua primeira requisição em curl, JavaScript e Python

Todo endpoint é uma requisição GET simples sob https://metalapi.com/api/v1/. O endpoint /latest retorna os preços atuais. base define a moeda em que os preços são expressos (padrão USD) e currencies limita a resposta aos símbolos de que você precisa. Uma requisição pode retornar muitos símbolos e continua contando como uma única requisição.

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

Uma resposta bem-sucedida tem esta aparência. Os números são os valores de exemplo usados em toda a documentação da MetalAPI, não preços ao vivo:

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319,
    "USDXAU": 3997.89,
    "XAG": 0.0185392857,
    "USDXAG": 53.94
  },
  "rate_limit": {
    "limit": 10000,
    "remaining": 9876,
    "reset": 1793491200,
    "used": 124,
    "plan": "Standard",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

A mesma chamada a partir do Node.js 18 ou mais recente, que já traz fetch embutido. Salve-a como gold.mjs para que o await no nível superior funcione e execute node gold.mjs:

const params = new URLSearchParams({ base: "USD", currencies: "XAU,XAG" });
const res = await fetch(`https://metalapi.com/api/v1/latest?${params}`, {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();

if (!data.success) {
  throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
}

const gold = data.rates[`${data.base}XAU`];
const asOf = new Date(data.timestamp * 1000).toISOString();
console.log(`Gold: ${gold} ${data.base} per troy ounce (data from ${asOf})`);

E a partir do Python, com a biblioteca requests:

import os

import requests

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": "XAU,XAG"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

base = data["base"]
print(f"Gold:   {data['rates'][base + 'XAU']} {base} per troy ounce")
print(f"Silver: {data['rates'][base + 'XAG']} {base} per troy ounce")

Os dois trechos montam a chave da cotação a partir de data.base, em vez de fixá-la no código. Esse pequeno hábito mantém o código correto quando você mudar a moeda base mais tarde, e leva à parte mais importante deste guia.

Leia o formato das cotações corretamente

Cada símbolo aparece duas vezes em rates, e os dois números são o inverso um do outro:

A regra geral: rates.<BASE><SYMBOL> é o preço de uma unidade do símbolo na moeda base. A chave simples rates.<SYMBOL> é o inverso: unidades do símbolo por uma unidade da base. A forma inversa é mantida por compatibilidade com APIs no estilo forex e com integrações antigas da MetalAPI.

Se você já armazena valores inversos de uma integração antiga, não precisa baixá-los de novo: preço = 1 ÷ inverso. Com o exemplo acima, 1 ÷ 0,0002501319 resulta novamente em 3.997,89, salvo os últimos dígitos de arredondamento.

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. O guia de formatos de dados traz mais exemplos, incluindo as chaves de bid e ask disponíveis a partir do plano Standard.

Moedas base e unidades

Para cotar o ouro em outra moeda, mude base. A chave da cotação muda junto: base=EUR retorna EURXAU, e base=INR retorna INRXAU. As cotações cruzadas vêm de um mesmo instantâneo, então o ouro em euros e o euro em dólares são sempre consistentes entre si.

Por padrão, os preços dos metais são por onça troy. O parâmetro unit os retorna por outra unidade de peso:

Esta requisição retorna ouro e prata em euros por grama. Quando unit não é a padrão, a resposta a repete em um campo unit no nível superior:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

unit afeta apenas os metais preciosos e industriais. Energia, moedas e cripto não são alterados por ele. Para os detalhes sobre onças troy, gramas, tolas e arredondamento, leia Onças troy, gramas e quilogramas. Se você vende joias, Preços do ouro por quilate explicados aborda os preços de 22K e 18K e o endpoint /carat.

Preços históricos do ouro

Os preços passados usam os mesmos parâmetros e o mesmo formato de resposta. O histórico começa em 2000 para metais e energia, em 04/01/1999 para moedas e em 2014 para cripto. Quatro endpoints atendem à maioria das necessidades:

• /YYYY-MM-DD (ou /historical?date=YYYY-MM-DD, ou /yesterday): preços de fechamento de um dia. Para fins de semana e feriados, é retornado o fechamento do pregão mais recente.
• /timeframe (alias /timeseries): fechamentos diários entre start_date e end_date, até 30 dias por requisição no Free e 365 dias nos planos pagos.
• /change: cotação inicial, cotação final e variação absoluta e percentual entre duas datas.
• /ohlc: abertura, máxima, mínima e fechamento de um dia.

# Ouro e prata no fechamento de 15 de janeiro de 2024
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Fechamentos diários do ouro em euros em setembro de 2026
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

Os preços de fechamento de dias passados não mudam, então armazene-os uma vez em vez de solicitá-los de novo. Preços históricos de ouro e prata via API mostra como paginar 25 anos de dados, armazená-los localmente e criar gráficos com eles. O guia de dados históricos traz um helper em JavaScript para intervalos longos.

Erros, cotas e limites dos planos

Uma requisição com falha retorna um status HTTP de erro e um corpo com success: false. O objeto error tem um code numérico, um type legível por máquina e um info legível por humanos. Tome decisões com base em code ou type, nunca no texto de info. Os erros de limite de requisições (104), de cota (105), de restrição do plano (106) e de período (207) também incluem uma upgrade_url:

{
  "success": false,
  "error": {
    "code": 106,
    "type": "plan_restriction",
    "info": "The carat endpoint requires a paid subscription plan",
    "upgrade_url": "https://metalapi.com/dashboard/billing"
  }
}

Os códigos que você tem mais chance de encontrar:

Toda resposta autenticada informa a sua cota, tanto nos cabeçalhos X-RateLimit-* quanto no objeto rate_limit do corpo. /usage e /symbols nunca contam para a cota, então o monitoramento pode chamá-los à vontade. Requisições rejeitadas com 104, 106, 107 ou erro do servidor não são cobradas, mas erros de validação são. O guia de tratamento de erros lista todos os códigos e inclui um helper de novas tentativas.

Os planos diferem principalmente no volume de requisições e em quão recentes são os preços:

O pagamento anual economiza até 25%. A página de preços sempre traz os detalhes atuais.

Cache e dicas para produção

Solicitar /latest com mais frequência do que o seu plano atualiza retorna os mesmos números e gasta cota à toa. Mantenha os preços mais recentes em cache por, no mínimo, o intervalo de atualização do seu plano, e guarde os dias passados em cache para sempre. Este helper em Python mantém os preços mais recentes em cache e continua servindo a última resposta válida se a API não puder ser acessada:

import os
import time

import requests

TTL_SECONDS = 600  # Plano Standard: os preços são atualizados a cada 10 minutos
session = requests.Session()
session.headers["X-API-Key"] = os.environ["METALAPI_KEY"]
_cache = {"at": 0.0, "data": None}


def latest_prices():
    now = time.monotonic()
    if _cache["data"] and now - _cache["at"] < TTL_SECONDS:
        return _cache["data"]
    try:
        r = session.get(
            "https://metalapi.com/api/v1/latest",
            params={"currencies": "XAU,XAG,XPT,XPD"},
            timeout=10,
        )
        data = r.json()
    except (requests.RequestException, ValueError):
        data = None
    if data and data.get("success"):
        _cache.update(at=now, data=data)
        return data
    if _cache["data"]:
        return _cache["data"]  # últimos preços válidos; exiba o timestamp deles
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

Mais alguns hábitos que mantêm uma integração barata e confiável:

• Peça todos os símbolos em uma só chamada. currencies=XAU,XAG,XPT,XPD custa uma requisição; quatro chamadas separadas custam quatro.
• Mantenha a chave no servidor. Se um navegador precisar chamar a API, use uma chave restrita por domínio. Para exibir preços em um site sem escrever código, um widget incorporável mantém a chave totalmente fora da página.
• Exiba o timestamp. timestamp é o horário dos dados, e não da sua requisição. Exiba-o ao lado do preço, principalmente quando você serve um valor em cache ou o mercado está fechado no fim de semana.
• Planeje o seu polling. Fazer polling a cada 10 minutos consome cerca de 4.500 requisições por mês, e a cada minuto, cerca de 45.000. A partir do plano Pro, você pode usar o stream em tempo real, e a partir do Advanced pode receber alertas de preço por webhook.
• Use timeouts e novas tentativas seletivas. Defina um timeout de cerca de 10 segundos, tente de novo o 104 depois do Retry-After e os erros 5xx com backoff, e nunca repita erros de validação.
• Valide os símbolos de antemão. Carregue /symbols uma vez na inicialização (é gratuito) e rejeite códigos desconhecidos antes que eles custem uma requisição.

Se você trabalha com assistentes de IA, o servidor MCP da MetalAPI em https://metalapi.com/mcp expõe os mesmos dados como ferramentas, para que Claude, ChatGPT, Cursor ou VS Code possam consultar preços e histórico do ouro dentro do seu plano; veja IA e MCP. Para todos os endpoints e parâmetros, a referência é a documentação da API.