Acessando dados históricos
Consulte preços diários desde 1999, busque intervalos de datas, compare duas datas, obtenha barras OHLC e analise tendências de preços com a MetalAPI.
Qual histórico está disponível
A MetalAPI armazena uma barra diária (abertura, máxima, mínima e fechamento) por símbolo e por dia:
- Moedas desde 1999
- Metais preciosos, metais industriais e energia desde 2000
- Cripto desde 2014
Os preços dos metais anteriores a outubro de 2026 são derivados dos contratos futuros de vencimento mais próximo, então podem diferir ligeiramente do preço à vista do mesmo dia. Todos os planos podem consultar o histórico completo. Os planos diferem apenas na quantidade de dias que uma única requisição de intervalo pode abranger.
Um único dia
Use a data como caminho, o endpoint /historical com um parâmetro date, ou /yesterday. A resposta contém os preços de fechamento desse dia (UTC). Para GET /api/v1/2026-10-01?currencies=XAU,XAG:
{
"success": true,
"timestamp": 1790812800,
"historical": true,
"date": "2026-10-01",
"base": "USD",
"rates": {
"XAU": 0.0002583044893,
"USDXAU": 3871.4,
"XAG": 0.02097315436,
"USDXAG": 47.68
}
}Intervalos de datas com /timeframe
/timeframe retorna uma entrada por dia entre start_date e end_date, indexada pela data. Para GET /api/v1/timeframe?start_date=2026-10-19&end_date=2026-10-23¤cies=XAU:
{
"success": true,
"timeframe": true,
"start_date": "2026-10-19",
"end_date": "2026-10-23",
"base": "USD",
"rates": {
"2026-10-19": { "XAU": 0.0002537298285, "USDXAU": 3941.2 },
"2026-10-20": { "XAU": 0.0002526049889, "USDXAU": 3958.75 },
"2026-10-21": { "XAU": 0.0002517369852, "USDXAU": 3972.4 },
"2026-10-22": { "XAU": 0.0002506642603, "USDXAU": 3989.4 },
"2026-10-23": { "XAU": 0.0002501319446, "USDXAU": 3997.89 }
}
}Dias sem preço de fechamento, como fins de semana ou feriados de mercado, podem estar ausentes. Não presuma uma entrada por dia do calendário. /timeseries é um alias que retorna "timeseries": true em vez de "timeframe": true.
Intervalos maiores do que o seu plano permite
Uma única requisição pode abranger até 30 dias no Free e 365 dias nos planos pagos. Intervalos maiores retornam o erro 207. Divida intervalos longos em blocos, em que cada bloco é uma requisição:
const DAY = 86_400_000;
const MAX_DAYS = 365; // 30 no plano Free
const iso = (d) => d.toISOString().slice(0, 10);
async function fetchRange(start, end, currencies) {
const rates = {};
let from = new Date(`${start}T00:00:00Z`);
const last = new Date(`${end}T00:00:00Z`);
while (from <= last) {
const to = new Date(Math.min(from.getTime() + MAX_DAYS * DAY, last.getTime()));
const params = new URLSearchParams({ start_date: iso(from), end_date: iso(to), currencies });
const res = await fetch(`https://metalapi.com/api/v1/timeframe?${params}`, {
headers: { "X-API-Key": process.env.METALAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
Object.assign(rates, data.rates);
from = new Date(to.getTime() + DAY);
}
return rates;
}
// Dez anos de preços diários do ouro em 10 requisições
const gold = await fetchRange("2016-01-01", "2025-12-31", "XAU");Variações entre duas datas
/change compara dois dias diretamente, então você não precisa baixar o intervalo entre eles. Para GET /api/v1/change?start_date=2026-09-30&end_date=2026-10-23¤cies=XAU:
{
"success": true,
"change": true,
"start_date": "2026-09-30",
"end_date": "2026-10-23",
"base": "USD",
"rates": {
"XAU": { "start_rate": 0.0002591613539, "end_rate": 0.0002501319446, "change": -0.000009029409258, "change_pct": -3.48409 },
"USDXAU": { "start_rate": 3858.6, "end_rate": 3997.89, "change": 139.29, "change_pct": 3.60986 }
}
}Use as chaves com prefixo, como USDXAU, para variações de preço. As chaves inversas se movem na direção oposta.
Barras OHLC diárias
/ohlc retorna a abertura, a máxima, a mínima e o fechamento de um dia, que é o que você precisa para gráficos de candlestick e amplitudes diárias. Para GET /api/v1/ohlc?date=2026-10-22¤cies=XAU:
{
"success": true,
"ohlc": true,
"date": "2026-10-22",
"base": "USD",
"rates": {
"USDXAU": { "open": 3962.1, "high": 4012.75, "low": 3951.3, "close": 3989.4 },
"XAU": { "open": 0.0002523914086, "high": 0.0002530812644, "low": 0.000249205657, "close": 0.0002506642603 }
}
}Conversões históricas
Adicione date a /convert para converter a um preço de fechamento passado. Por exemplo, esta requisição mostra quanto valiam 10 onças troy de prata em euros em 1º de outubro de 2026:
GET /api/v1/convert?api_key=YOUR_API_KEY&from=XAG&to=EUR&amount=10&date=2026-10-01Analisando tendências
A resposta de /timeframe é fácil de transformar em uma série. Este exemplo calcula uma média móvel simples de 20 dias do preço do ouro:
// data = resposta de /timeframe?currencies=XAU
const series = Object.entries(data.rates)
.sort(([a], [b]) => a.localeCompare(b))
.map(([date, rates]) => ({ date, price: rates.USDXAU }));
function movingAverage(points, period) {
return points.slice(period - 1).map((point, i) => ({
date: point.date,
sma: points.slice(i, i + period).reduce((sum, p) => sum + p.price, 0) / period,
}));
}
const sma20 = movingAverage(series, 20);Os preços de fechamento de dias passados nunca mudam, então armazene-os permanentemente em vez de solicitá-los novamente. Apenas a barra de hoje ainda está em movimento.
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.