Primeiros passos com a MetalAPI

Introdução

A MetalAPI é uma API REST em JSON para cotações à vista de metais preciosos, metais industriais, energia, cerca de 55 moedas e 13 criptomoedas. Ela fornece cotações em tempo real, histórico diário desde 1999, conversões, barras OHLC e preços do ouro por quilate.

Todo endpoint é uma requisição HTTPS GET simples sob https://metalapi.com/api/v1, então funciona com qualquer linguagem ou cliente HTTP. Este guia leva você do cadastro à sua primeira resposta em poucos minutos.

Obtenha sua chave de API

Crie uma conta grátis com o seu endereço de e-mail. Não é preciso cartão de crédito. O plano Free inclui 100 requisições por mês com atualização diária dos preços, o suficiente para experimentar a API.

Abra API keys no painel e crie uma chave. As chaves começam com mk_live_ seguido de 32 caracteres. Armazenamos apenas um hash de cada chave, então a chave completa é exibida uma única vez. Copie-a imediatamente para o seu gerenciador de senhas ou para as suas variáveis de ambiente.

Faça sua primeira requisição

Solicite os preços mais recentes dos quatro metais preciosos em dólares americanos. Substitua YOUR_API_KEY pela sua chave:

curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY&base=USD&currencies=XAU,XAG,XPT,XPD"

Entenda a resposta

base é a moeda em que os preços são expressos (padrão USD). currencies limita a resposta aos símbolos de que você precisa. Omita-o para receber todos os símbolos em uma única resposta. Uma chamada bem-sucedida retorna um JSON como este:

{
  "success": true,
  "timestamp": 1792713600,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "XAG": 0.01853911754,
    "USDXAG": 53.94,
    "XPT": 0.000620212733,
    "USDXPT": 1612.35,
    "XPD": 0.0006775985906,
    "USDXPD": 1475.8
  },
  "rate_limit": {
    "limit": 100,
    "remaining": 99,
    "reset": 1793491200,
    "used": 1,
    "plan": "Free",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

Cada símbolo aparece duas vezes. USDXAU é o preço de uma onça troy de ouro na moeda base, que geralmente é o número que você quer exibir. XAU é o inverso: quantas onças troy um dólar americano compra. O guia de formatos de dados explica as duas direções em detalhes.

O bloco rate_limit, também enviado nos cabeçalhos X-RateLimit-*, mostra quanto ainda resta da sua cota mensal e quando ela é renovada.

Chame a API pelo código

Aqui está a mesma requisição em JavaScript (Node.js 18+, Deno ou Bun). Desta vez, a chave é enviada em um cabeçalho em vez de na URL:

const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
});
const data = await res.json();

if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
console.log("Gold, USD per troy ounce:", data.rates.USDXAU);

Próximos passos

• Autenticação: chaves enviadas por cabeçalho e chaves restritas por domínio para uso no navegador.
• Endpoints disponíveis: cotações históricas, conversão, séries temporais, OHLC e preços por quilate.
• Limites de requisições e planos: cotas, limites por minuto e intervalos de atualização.
• Tratamento de erros: códigos de erro e uma estratégia sensata de novas tentativas.