Precios del cobre, el aluminio, el zinc y el petróleo por API: guía para desarrolladores

Los símbolos industriales y de energía

Los metales preciosos acaparan la mayoría de los titulares, pero a muchas empresas les importan más el cobre, el aluminio, el acero y el combustible. De ellos depende el coste de los cables y los motores, de las latas y las carrocerías, del acero de construcción y de cada camión que transporta mercancías. MetalAPI cotiza cuatro metales industriales y cinco contratos de energía junto al oro y la plata, con los mismos endpoints y el mismo formato de respuesta.

La página de símbolos los enumera con precios en tiempo real, y GET /api/v1/symbols?details=1 devuelve en JSON la categoría y la unidad de cada símbolo. Esa llamada es gratuita y no cuenta para tu cuota.

Unidades de mercado frente a la normalización de la API

Cada uno de estos mercados tiene su propia convención. En Nueva York, el cobre se negocia por libra; el aluminio y el zinc, por tonelada métrica; el acero estadounidense, por tonelada corta; el petróleo crudo, por barril; el gas natural, por millón de unidades térmicas británicas (MMBtu), y los productos refinados, por galón. Si los confundes, tus cifras se desvían en un factor de mil o más.

MetalAPI normaliza los metales y deja la energía en sus unidades de contrato:

• Todos los metales, preciosos e industriales, se cotizan por onza troy de forma predeterminada. Así todos los metales se pueden comparar directamente y cualquiera de ellos se convierte con un solo parámetro. Nadie negocia el cobre por onza troy, así que para los metales industriales casi siempre pasarás unit.
• La energía se cotiza por unidad de contrato: barriles para WTI y BRENT, MMBtu para NATURALGAS y galones estadounidenses para GASOLINE y HEATINGOIL. El parámetro unit no se aplica a la energía, las divisas ni las criptomonedas.

unit acepta troy_oz (por defecto), gram, kilogram, ounce, pound, metric_ton y short_ton. Para obtener cada metal en la unidad que usa su mercado:

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

# Aluminio y zinc en 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 acero laminada en caliente en USD por tonelada corta
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cuando se usa una unidad distinta de la predeterminada, la respuesta lo indica en un campo unit. El precio que buscas es la clave con el prefijo de la divisa base (USDXCU); la clave simple XCU es su inverso y se mantiene por compatibilidad con integraciones antiguas:

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

Precios basados en futuros y qué significa el primer vencimiento

El oro al contado se negocia fuera de bolsa las 24 horas, pero los precios más transparentes de los metales industriales y la energía se forman en las bolsas de futuros. MetalAPI toma estos precios de COMEX y NYMEX (ambas parte de CME Group) y de ICE. Un contrato de futuros es un acuerdo estandarizado para comprar o vender una cantidad fija a un precio fijo con entrega en un mes concreto. Cada mes de entrega es un contrato distinto con su propio precio.

El primer vencimiento (front month) es el mes de entrega más cercano que todavía se negocia. Una serie continua del primer vencimiento sigue ese contrato hasta que se acerca su vencimiento y entonces pasa al siguiente, lo que se conoce como roll o renovación. Hay tres consecuencias que importan a los desarrolladores:

• Saltos por el cambio de contrato. En la fecha del roll, la serie puede saltar, no porque se haya movido el mercado, sino porque el siguiente contrato cotiza a otro precio. Cuando los meses posteriores son más caros (contango), la serie sube de golpe; cuando son más baratos (backwardation), baja. Tenlo en cuenta antes de lanzar alertas por la variación de un día en torno al vencimiento.
• Una bolsa no es todo el mercado. El precio del cobre de COMEX es un precio de una bolsa estadounidense. Gran parte del cobre, el aluminio y el zinc físicos del mundo se cotiza con referencia a la London Metal Exchange, y las entregas físicas añaden primas regionales, fletes e impuestos. Los precios de los distintos mercados se siguen de cerca, pero no exactamente. Si un contrato de suministro fija una referencia concreta, como un precio oficial de la LME o una evaluación de precios publicada, esa referencia es la que manda en tu factura. Una fuente de futuros de una bolsa es una buena herramienta para hacer seguimiento y estimaciones, no un sustituto del índice contractual.
• Horario de negociación. Estos contratos siguen el horario de sus bolsas: casi las 24 horas desde el domingo por la tarde hasta el viernes por la tarde, hora de Nueva York, con una breve pausa diaria. Durante el fin de semana, MetalAPI sigue devolviendo el último precio.

Como proceden de futuros, estos símbolos se publican con un único precio; los sufijos bid y ask no están disponibles para ellos. El historial diario de los metales y la energía se remonta a 2000, y la guía de datos históricos muestra cómo consultar precios de cierre, rangos y barras OHLC.

Conversión de unidades y divisas

Si necesitas varios metales en distintas unidades, lo más barato es hacer una solicitud en onzas troy y convertir en tu propio código. Una solicitud de datos cuenta una vez sin importar cuántos símbolos devuelva, así que cuesta una solicitud en lugar de tres. Las constantes de abajo se deducen de las definiciones de las unidades:

// Onzas troy en una unidad de masa
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 onza troy
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

Las divisas funcionan igual para los metales y la energía. Añade base=EUR, o cualquiera de las 57 divisas admitidas, y todos los precios de la respuesta se expresan en esa divisa, convertidos a partir de la misma instantánea. Para valorar una cantidad directamente, /convert acepta un importe y una unidad:

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

Las conversiones de energía se hacen en tu código. Algunos factores estándar útiles: un barril son 42 galones estadounidenses, unos 158,987 litros; un galón estadounidense son 3,785411784 litros; un MMBtu equivale a unos 1,055 gigajulios, 293,07 kWh o 10 therms. Convertir barriles de petróleo crudo a toneladas depende de la densidad del crudo, así que usa el factor del tipo de crudo que compras realmente.

Caso de uso: compras y seguimiento de costes

Los equipos de compras usan los precios de las bolsas para entender hacia dónde se mueven los costes de sus insumos y para comprobar si las ofertas de los proveedores son razonables. Los componentes típicos:

• Un panel diario del cobre, el aluminio, el acero y el gasóleo en las unidades y la divisa que usan tus contratos.
• La variación entre periodos con /change, que devuelve en una sola solicitud el precio inicial, el precio final, la variación absoluta y la variación porcentual entre dos fechas para cada símbolo.
• Alertas por umbral. En los planes de pago, las alertas de precio del panel envían un correo electrónico, y desde el plan Advanced también un webhook firmado, cuando un precio cruza un nivel o se mueve un determinado porcentaje. Es una forma sencilla de desencadenar la revisión de una hipótesis presupuestaria.
• Revisión de ofertas. Comparar el contenido de metal del precio de un proveedor con la referencia de la bolsa muestra qué parte de una variación de precio procede del metal y cuál de las primas o la transformación.

# Cobre y aluminio por tonelada métrica: variación en septiembre 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"

Ten presente la advertencia anterior: si un contrato está indexado a un precio publicado concreto, concilia con ese índice todo lo que acabe en una factura.

Caso de uso: modelos de costes de fabricación

Una lista de materiales suele indicar el contenido de metal en kilogramos. Como unit acepta kilogram para todos los metales, una sola solicitud devuelve el precio por kilogramo de todos ellos, en la divisa de tus informes:

import os
import requests

# Contenido de metal por unidad de producto, en 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']})")

Dos mejoras hacen más útil un modelo así. Primero, guarda el precio, la unidad y la marca de tiempo que usaste junto a cada cálculo de costes, para poder explicar más tarde por qué cambió un coste. Segundo, plantéate usar una media de un periodo en lugar de un único precio actual; suaviza el ruido diario y los saltos por cambio de contrato. /timeframe devuelve cierres diarios de hasta 365 días por solicitud en los planes de pago (30 días en Free), suficiente para una media mensual o trimestral en una sola llamada.

Caso de uso: logística y costes de combustible

El combustible es el mayor coste variable para muchos transportistas, y los recargos por combustible suelen recalcularse cada semana o cada mes. HEATINGOIL, el contrato de diésel de ultrabajo contenido en azufre de NY Harbor, es una referencia mayorista del diésel muy seguida. GASOLINE (RBOB) cumple la misma función para la gasolina, y WTI y BRENT cubren el petróleo crudo.

Los futuros mayoristas y los precios en surtidor son cosas distintas: los precios al público añaden costes de distribución, márgenes e impuestos, y siguen a los futuros con retraso. Muchas tablas de recargos se basan en una media publicada de precios al público y, si la tuya lo hace, esa media es la cifra que debes usar. Aun así, los datos de futuros son útiles para el seguimiento interno de costes y para ver pronto los movimientos en origen.

Este ejemplo calcula la media de los cierres diarios de la semana pasada del contrato de diésel y convierte el resultado de USD por galón a 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 usa la fecha como clave; faltan los días sin cierre (fines de semana, festivos)
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");

Consejos prácticos

• Consulta al ritmo de tu plan, no más rápido. Free recibe precios diarios; Lite, cada 30 minutos; Standard, cada 10 minutos; Advanced y Pro, cada minuto; Ultra y Business, cada 15 segundos, y Enterprise, cada 5 segundos. Las solicitudes intermedias devuelven la misma instantánea y aun así cuentan. Desde Pro, el stream en tiempo real sustituye a las consultas periódicas.
• Agrupa los símbolos. Una solicitud puede devolver los nueve símbolos industriales y de energía, y cuesta lo mismo que una solicitud de uno solo.
• Guarda lo que obtienes. Almacena cada precio con su símbolo, su unidad, su divisa base y su timestamp. Convertir después es fácil; adivinar la unidad de una cifra antigua, no.
• Cuenta con huecos en el historial. Las series diarias omiten los fines de semana y los festivos de las bolsas, así que no supongas que hay una entrada por cada día del calendario.
• Divide los rangos largos. Una sola solicitud a /timeframe cubre hasta 365 días en los planes de pago, así que recorre el historial año a año si necesitas remontarte hasta 2000.
• Valida antes de enviar. Las solicitudes rechazadas por fechas, símbolos o unidades no válidos cuentan igualmente para tu cuota, así que compruébalos antes en tu código. Los rechazos por límite de solicitudes y los errores del servidor no se facturan.

Para empezar, regístrate y obtén una clave gratuita, consulta la página de símbolos para ver los precios industriales y de energía en tiempo real, y revisa la documentación de la API para conocer todos los endpoints y parámetros. La página de precios indica el intervalo de actualización y la cuota de cada plan.