Visão geral da documentação da API
Um tour em uma página pela API REST da MetalAPI: URL base, autenticação, parâmetros, formato de resposta, erros, limites de requisições e exemplos de código.
URL base
Todas as requisições vão para https://metalapi.com/api/v1/ via HTTPS e usam GET. As respostas são em JSON, com um indicador success.
Esta página é um tour rápido. A referência completa, com todos os parâmetros, está na documentação da API.
Autenticação
Envie a sua chave de API como parâmetro de consulta, como token Bearer ou em um cabeçalho X-API-Key. As chaves têm o formato mk_live_ seguido de 32 caracteres. Mantenha-as em segredo; veja Autenticação.
# Parâmetro de consulta
GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY
# Cabeçalho Authorization
GET https://metalapi.com/api/v1/latest
Authorization: Bearer YOUR_API_KEY
# Cabeçalho X-API-Key
GET https://metalapi.com/api/v1/latest
X-API-Key: YOUR_API_KEYEndpoints
/latest: preços atuais/{YYYY-MM-DD},/yesterdayou/historical?date=: preços de fechamento de um dia passado/convert?from=&to=&amount=: converte qualquer valor, opcionalmente em umadatepassada/timeframe?start_date=&end_date=(alias/timeseries): preços diários de um intervalo de datas/change?start_date=&end_date=: variação entre dois dias/ohlc?date=: abertura, máxima, mínima e fechamento de um dia/carat?carat=24oucarat=all: preços do ouro por quilate (planos pagos)/symbols: símbolos suportados (gratuito, não consome cota)/usage: a sua cota (gratuito, não consome cota)/stream: Server-Sent Events em tempo real (a partir do plano Pro)
Os parâmetros e exemplos de cada um estão em Endpoints disponíveis.
Parâmetros da requisição
api_key: a sua chave, a menos que você a envie em um cabeçalhobase: a moeda dos preços retornados,USDpor padrãocurrenciesousymbols: símbolos separados por vírgula a serem retornados. Todos os símbolos por padrão.unit: unidade de massa para os metais. Um destes:troy_oz(padrão),gram,kilogram,ounce,pound,metric_tonoushort_ton.
GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR¤cies=XAU,XAG,USD,GBP&unit=gramFormato da resposta
As respostas bem-sucedidas incluem success: true, os dados e um bloco rate_limit. Cada símbolo aparece duas vezes: XAU (onças troy por uma unidade da moeda base) e USDXAU (o preço de uma onça troy na moeda base). Veja Formatos de dados e unidades.
{
"success": true,
"timestamp": 1792765800,
"date": "2026-10-23",
"base": "USD",
"rates": {
"EUR": 0.8589589418,
"USDEUR": 1.1642,
"XAG": 0.01853911754,
"USDXAG": 53.94,
"XAU": 0.0002501319446,
"USDXAU": 3997.89
},
"rate_limit": {
"limit": 10000,
"remaining": 9876,
"reset": 1793491200,
"used": 124,
"plan": "Standard",
"reset_date": "2026-11-01T00:00:00.000Z"
}
}Erros
Os erros retornam um status HTTP de erro e um corpo success: false com um código numérico, um tipo e uma mensagem. A lista completa está em Tratamento de erros.
{
"success": false,
"error": {
"code": 102,
"type": "invalid_api_key",
"info": "User did not supply an access key or supplied an invalid access key"
}
}Limitação de requisições
Cada plano tem uma cota mensal, renovada no dia 1º às 00:00 UTC, e um limite por minuto. Toda resposta autenticada inclui:
X-RateLimit-Limit,X-RateLimit-RemainingeX-RateLimit-Usedpara a cota mensalX-RateLimit-ReseteX-RateLimit-Reset-Datepara o momento em que a cota é renovadaX-RateLimit-Plancom o nome do seu planoX-RateLimit-Minute-LimiteX-RateLimit-Minute-Remainingpara o limite por minuto
Os mesmos valores estão no bloco JSON rate_limit. Veja Limites de requisições e planos.
Símbolos suportados
- Metais preciosos:
XAU,XAG,XPT,XPD - Metais industriais:
XCU,ALU,ZNC,HRC - Energia:
WTI,BRENT,NATURALGAS,GASOLINE,HEATINGOIL - Moedas: cerca de 55, incluindo
USD,EUR,GBP,JPY,CHF,CAD,AUDeCNY - Cripto: 13 moedas, incluindo
BTC,ETH,SOL,USDTeUSDC
Veja todos na página de símbolos.
Exemplo em Node.js
Usando o fetch nativo (Node.js 18+):
const API_KEY = process.env.METALAPI_KEY;
const BASE_URL = "https://metalapi.com/api/v1";
async function getLatestRates(currencies = "XAU,XAG,EUR") {
const res = await fetch(`${BASE_URL}/latest?currencies=${currencies}`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
return data.rates;
}
const rates = await getLatestRates();
console.log("Gold (USD/oz):", rates.USDXAU);
console.log("Silver (USD/oz):", rates.USDXAG);Exemplo em PHP
Usando PHP com cURL:
<?php
$apiKey = getenv('METALAPI_KEY');
$curl = curl_init('https://metalapi.com/api/v1/latest?currencies=XAU,XAG');
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ["X-API-Key: {$apiKey}"],
]);
$response = curl_exec($curl);
$error = curl_error($curl);
curl_close($curl);
if ($error) {
exit("cURL error: {$error}\n");
}
$data = json_decode($response, true);
if (!$data['success']) {
exit("API error {$data['error']['code']}: {$data['error']['info']}\n");
}
echo "Gold (USD/oz): " . $data['rates']['USDXAU'] . "\n";
echo "Silver (USD/oz): " . $data['rates']['USDXAG'] . "\n";Exemplo em Python
Usando a biblioteca requests:
import os
import requests
API_KEY = os.environ["METALAPI_KEY"]
BASE_URL = "https://metalapi.com/api/v1"
def get_metal_rates(currencies="XAU,XAG,XPT"):
"""Busca os preços mais recentes dos metais na MetalAPI."""
response = requests.get(
f"{BASE_URL}/latest",
params={"currencies": currencies},
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = response.json()
if not data["success"]:
raise RuntimeError(f"{data['error']['code']}: {data['error']['info']}")
return data["rates"]
rates = get_metal_rates()
print(f"Gold: {rates['USDXAU']} USD/oz")
print(f"Silver: {rates['USDXAG']} USD/oz")
print(f"Platinum: {rates['USDXPT']} USD/oz")Exemplo de requisição
Convertendo 1.000 dólares americanos em onças troy de ouro:
curl "https://metalapi.com/api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000"Exemplo de resposta
result é o valor convertido e info.rate é a cotação aplicada:
{
"success": true,
"query": { "from": "USD", "to": "XAU", "amount": 1000 },
"info": { "timestamp": 1792765800, "rate": 0.0002501319446, "quote": 0.0002501319446 },
"date": "2026-10-23",
"result": 0.2501319446,
"rate_limit": {
"limit": 10000,
"remaining": 9876,
"reset": 1793491200,
"used": 124,
"plan": "Standard",
"reset_date": "2026-11-01T00:00:00.000Z"
}
}Guias relacionados
Pronto para começar a desenvolver?
Crie uma conta grátis para obter sua chave de API ou explore todos os endpoints na referência da API.