Preços de cobre, alumínio, zinco e petróleo via API: guia para desenvolvedores

Os símbolos de metais industriais e energia

Os metais preciosos ficam com a maior parte das manchetes, mas muitas empresas se importam mais com cobre, alumínio, aço e combustível. Eles determinam o custo de cabos e motores, latas e carrocerias, aço para construção e de cada caminhão que transporta mercadorias. A MetalAPI cota quatro metais industriais e cinco contratos de energia ao lado do ouro e da prata, pelos mesmos endpoints e no mesmo formato de resposta.

A página de símbolos lista todos eles com preços ao vivo, e GET /api/v1/symbols?details=1 retorna a categoria e a unidade de cada símbolo em JSON. Essa chamada é gratuita e não conta para a sua cota.

Unidades naturais e a normalização da API

Cada um desses mercados tem a sua própria convenção. Em Nova York, o cobre é negociado por libra; o alumínio e o zinco por tonelada métrica, o aço americano por tonelada curta, o petróleo bruto por barril, o gás natural por milhão de unidades térmicas britânicas (MMBtu) e os derivados refinados por galão. Misture-os e os seus números ficam errados por um fator de mil ou mais.

A MetalAPI normaliza os metais e mantém a energia nas suas unidades de contrato:

• Todos os metais, preciosos e industriais, são cotados por onça troy por padrão. Isso mantém todos os metais diretamente comparáveis e permite converter qualquer um deles com um único parâmetro. Cobre por onça troy não é um número que alguém negocie, então, para metais industriais, você quase sempre vai passar unit.
• A energia é cotada por unidade de contrato: barris para WTI e BRENT, MMBtu para NATURALGAS e galões americanos para GASOLINE e HEATINGOIL. O parâmetro unit não se aplica a energia, moedas nem cripto.

unit aceita troy_oz (o padrão), gram, kilogram, ounce, pound, metric_ton e short_ton. Para obter cada metal na unidade usada pelo seu mercado:

# Cobre em USD por libra
curl "https://metalapi.com/api/v1/latest?currencies=XCU&unit=pound" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Alumínio e zinco em USD por tonelada métrica
curl "https://metalapi.com/api/v1/latest?currencies=ALU,ZNC&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Bobina de aço laminada a quente em USD por tonelada curta
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Quando uma unidade diferente da padrão é usada, a resposta informa isso em um campo unit. O preço que você quer é a chave com o prefixo da moeda base (USDXCU); a chave simples XCU é o seu inverso, mantido por compatibilidade com integrações antigas:

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "unit": "pound",
  "rates": {
    "XCU": 0.2222222222,
    "USDXCU": 4.5
  }
}

Preços baseados em futuros e o que significa vencimento mais próximo

O ouro à vista é negociado no mercado de balcão 24 horas por dia, mas os metais industriais e a energia têm a formação de preço mais transparente nas bolsas de futuros. A MetalAPI obtém esses preços da COMEX e da NYMEX (ambas parte do CME Group) e da ICE. Um contrato futuro é um acordo padronizado para comprar ou vender uma quantidade definida a um preço definido, com entrega em um mês específico. Cada mês de entrega é um contrato separado, com o seu próprio preço.

O vencimento mais próximo (front month) é o mês de entrega mais próximo que ainda está sendo negociado. Uma série contínua de vencimento mais próximo acompanha esse contrato até que ele se aproxime do vencimento e depois passa, ou rola, para o seguinte. Três consequências importam para desenvolvedores:

• Degraus de rolagem. Em uma data de rolagem, a série pode saltar, não porque o mercado se moveu, mas porque o contrato seguinte é negociado a outro preço. Quando os meses seguintes são mais caros (contango), a série sobe um degrau; quando são mais baratos (backwardation), ela desce. Tenha isso em mente antes de disparar alertas por uma variação de um dia perto do vencimento.
• Uma bolsa não é o mercado inteiro. Um preço do cobre da COMEX é um preço de bolsa americana. Grande parte do cobre, do alumínio e do zinco físicos do mundo é precificada com base na London Metal Exchange, e as entregas físicas acrescentam prêmios regionais, frete e impostos. Os preços em diferentes praças se acompanham de perto, mas não exatamente. Se um contrato de fornecimento cita uma referência específica, como um preço oficial da LME ou uma avaliação de preço publicada, é essa referência que vale para a sua fatura. Um feed de futuros de bolsa é uma boa ferramenta para monitorar e estimar, não um substituto do índice contratual.
• Horários de negociação. Esses contratos seguem os horários das suas bolsas: quase 24 horas por dia, de domingo à noite até sexta-feira à tarde, no horário de Nova York, com uma breve pausa diária. No fim de semana, a MetalAPI continua retornando o último preço.

Como vêm de futuros, esses símbolos são publicados com um único preço; os sufixos de bid e ask não estão disponíveis para eles. O histórico diário de metais e energia vai até 2000, e o guia de dados históricos mostra como consultar preços de fechamento, intervalos e barras OHLC.

Convertendo unidades e moedas

Se você precisa de vários metais em unidades diferentes, a abordagem mais barata é uma requisição em onças troy e a conversão no seu próprio código. Uma requisição de dados conta uma única vez, não importa quantos símbolos ela retorne, então isso custa uma requisição em vez de três. As constantes abaixo decorrem das definições das unidades:

// Onças troy em uma unidade de massa
const GRAMS_PER_TROY_OZ = 31.1034768;
const TROY_OZ_PER = {
  lb: 453.59237 / GRAMS_PER_TROY_OZ,        // 14.5833…
  short_ton: 907184.74 / GRAMS_PER_TROY_OZ, // 29,166.67…
  metric_ton: 1e6 / GRAMS_PER_TROY_OZ,      // 32,150.75…
};

const NATURAL_UNIT = { XCU: "lb", ALU: "metric_ton", ZNC: "metric_ton", HRC: "short_ton" };

const url = new URL("https://metalapi.com/api/v1/latest");
url.searchParams.set("currencies", Object.keys(NATURAL_UNIT).join(","));

const res = await fetch(url, { 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);

for (const [symbol, unit] of Object.entries(NATURAL_UNIT)) {
  const perTroyOz = data.rates["USD" + symbol]; // USD por onça troy
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

As moedas funcionam da mesma forma para metais e energia. Adicione base=EUR, ou qualquer uma das 57 moedas suportadas, e todos os preços da resposta são expressos nessa moeda, convertidos a partir do mesmo instantâneo. Para avaliar uma quantidade diretamente, /convert recebe um valor e uma unidade:

# 25 toneladas métricas de cobre em euros
curl "https://metalapi.com/api/v1/convert?from=XCU&to=EUR&amount=25&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

As conversões de energia acontecem no seu código. Fatores padrão úteis: um barril tem 42 galões americanos, ou cerca de 158,987 litros; um galão americano tem 3,785411784 litros; um MMBtu equivale a cerca de 1,055 gigajoule, 293,07 kWh ou 10 therms. A conversão de barris de petróleo bruto em toneladas depende da densidade do óleo, então use o fator do tipo que você realmente compra.

Caso de uso: compras e monitoramento de custos

As equipes de compras usam preços de bolsa para entender para onde vão os custos dos insumos e para conferir as cotações dos fornecedores. Os componentes típicos:

• Um painel diário de cobre, alumínio, aço e diesel nas unidades e na moeda que os seus contratos usam.
• Variação entre períodos com /change, que retorna o preço inicial, o preço final, a variação absoluta e a variação percentual entre duas datas para cada símbolo em uma única requisição.
• Alertas de limiar. Nos planos pagos, os alertas de preço do painel enviam um e-mail e, a partir do plano Advanced, também um webhook assinado quando um preço cruza um nível ou varia uma determinada porcentagem. É uma forma simples de disparar a revisão de uma premissa do orçamento.
• Conferência de cotações. Comparar o conteúdo de metal do preço de um fornecedor com a referência de bolsa mostra quanto de uma variação de preço vem do metal e quanto vem de prêmios ou do processamento.

# Cobre e alumínio por tonelada métrica: variação em setembro de 2026
curl "https://metalapi.com/api/v1/change?currencies=XCU,ALU&unit=metric_ton&start_date=2026-09-01&end_date=2026-09-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Lembre-se da ressalva anterior: se um contrato estiver indexado a um preço publicado específico, faça a conciliação com esse índice para tudo o que for parar em uma fatura.

Caso de uso: modelos de custo de fabricação

Uma lista de materiais normalmente informa o conteúdo de metal em quilogramas. Como unit aceita kilogram para todos os metais, uma única requisição retorna o preço por quilograma de todos eles, na sua moeda de relatório:

import os
import requests

# Conteúdo de metal por unidade de produto, em kg (ilustrativo)
BOM = {"XCU": 1.20, "ALU": 0.85, "ZNC": 0.05}

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"currencies": ",".join(BOM), "unit": "kilogram", "base": "EUR"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data.get("success"):
    raise RuntimeError(data["error"])

total = 0.0
for symbol, kg in BOM.items():
    eur_per_kg = data["rates"]["EUR" + symbol]
    cost = kg * eur_per_kg
    total += cost
    print(f"{symbol}: {kg} kg x {eur_per_kg:.4f} EUR/kg = {cost:.2f} EUR")

print(f"Metal content per unit: {total:.2f} EUR (prices of {data['date']})")

Dois refinamentos tornam um modelo como esse mais útil. Primeiro, armazene o preço, a unidade e o timestamp usados ao lado de cada cálculo de custo, para poder explicar depois por que um custo mudou. Segundo, considere uma média ao longo de um período em vez de um único preço mais recente; ela suaviza o ruído diário e os degraus de rolagem. /timeframe retorna fechamentos diários de até 365 dias por requisição nos planos pagos (30 dias no Free), o que basta para uma média mensal ou trimestral em uma única chamada.

Caso de uso: logística e custos de combustível

O combustível é o maior custo variável de muitas transportadoras, e as sobretaxas de combustível costumam ser recalculadas semanal ou mensalmente. HEATINGOIL, o contrato de diesel com ultrabaixo teor de enxofre de NY Harbor, é uma referência de diesel no atacado muito acompanhada. GASOLINE (RBOB) cumpre o mesmo papel para a gasolina, e WTI e BRENT cobrem o petróleo bruto.

Futuros no atacado e preços na bomba são coisas diferentes: os preços de varejo acrescentam custos de distribuição, margens e impostos, e acompanham os futuros com atraso. Muitas tabelas de sobretaxa usam como referência uma média de varejo publicada e, se esse for o seu caso, é essa média que você deve usar. Os dados de futuros continuam úteis para o acompanhamento interno de custos e para perceber cedo os movimentos na origem da cadeia.

Este exemplo calcula a média dos fechamentos diários da semana passada do contrato de diesel e converte o resultado de USD por galão para EUR por litro:

const LITRES_PER_GALLON = 3.785411784;

const url = new URL("https://metalapi.com/api/v1/timeframe");
url.searchParams.set("currencies", "HEATINGOIL");
url.searchParams.set("base", "EUR");
url.searchParams.set("start_date", "2026-10-19");
url.searchParams.set("end_date", "2026-10-23");

const res = await fetch(url, { 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);

// rates é indexado por data; dias sem fechamento (fins de semana, feriados) ficam de fora
const closes = Object.values(data.rates).map((day) => day.EURHEATINGOIL);
const avgPerGallon = closes.reduce((sum, p) => sum + p, 0) / closes.length;

console.log("Average:", (avgPerGallon / LITRES_PER_GALLON).toFixed(4), "EUR per litre");

Dicas práticas

• Faça polling no intervalo do seu plano, não mais rápido. O Free vê preços diários, o Lite a cada 30 minutos, o Standard a cada 10 minutos, o Advanced e o Pro a cada minuto, o Ultra e o Business a cada 15 segundos e o Enterprise a cada 5 segundos. Requisições no meio do intervalo retornam o mesmo instantâneo e continuam contando. A partir do Pro, o stream em tempo real substitui o polling.
• Agrupe os símbolos. Uma requisição pode retornar todos os nove símbolos de metais industriais e energia, e custa o mesmo que uma requisição para um só.
• Armazene o que você buscou. Guarde cada preço com o seu símbolo, unidade, moeda base e timestamp. Converter depois é fácil; adivinhar a unidade de um número antigo, não.
• Espere lacunas no histórico. As séries diárias pulam fins de semana e feriados das bolsas, então não presuma uma entrada por dia do calendário.
• Divida intervalos longos. Uma única requisição a /timeframe cobre até 365 dias nos planos pagos, então faça um loop ano a ano para históricos mais longos, até 2000.
• Valide antes de enviar. Requisições rejeitadas por datas, símbolos ou unidades inválidos continuam contando para a sua cota, então verifique-os primeiro no seu código. Rejeições por limite de requisições e erros do servidor não são cobrados.

Para começar, cadastre-se e obtenha uma chave grátis, confira os preços ao vivo de metais industriais e energia na página de símbolos e consulte a documentação da API para todos os endpoints e parâmetros. A página de preços lista o intervalo de atualização e a cota de cada plano.