Цены на медь, алюминий, цинк и нефть через API: руководство для разработчиков

Символы промышленных металлов и энергоносителей

Больше всего внимания в новостях достаётся драгоценным металлам, но для многих компаний важнее медь, алюминий, сталь и топливо. От них зависит стоимость кабелей и двигателей, банок и кузовов автомобилей, строительной стали и каждого грузовика, который перевозит товары. Наряду с золотом и серебром MetalAPI котирует четыре промышленных металла и пять энергетических контрактов — через те же эндпоинты и в том же формате ответа.

На странице символов они перечислены с текущими ценами, а GET /api/v1/symbols?details=1 возвращает категорию и единицу каждого символа в формате JSON. Этот вызов бесплатен и не расходует квоту.

Рыночные единицы и нормализация в API

У каждого из этих рынков свои соглашения. В Нью-Йорке медь торгуется за фунт; алюминий и цинк — за метрическую тонну, американская сталь — за короткую тонну, сырая нефть — за баррель, природный газ — за миллион британских тепловых единиц (MMBtu), а нефтепродукты — за галлон. Перепутайте их — и ваши числа ошибутся в тысячу раз или больше.

MetalAPI нормализует металлы, а энергоносители оставляет в единицах контракта:

• Все металлы, драгоценные и промышленные, по умолчанию котируются за тройскую унцию. Так любые металлы можно напрямую сравнивать между собой и пересчитывать одним параметром. Медь за тройскую унцию никто не торгует, поэтому для промышленных металлов вы почти всегда будете передавать unit.
• Энергоносители котируются за единицу контракта: баррели для WTI и BRENT, MMBtu для NATURALGAS, галлоны США для GASOLINE и HEATINGOIL. Параметр unit не действует на энергоносители, валюты и криптовалюты.

unit принимает значения troy_oz (по умолчанию), gram, kilogram, ounce, pound, metric_ton и short_ton. Чтобы получить каждый металл в единице, принятой на его рынке:

# Copper in USD per pound
curl "https://metalapi.com/api/v1/latest?currencies=XCU&unit=pound" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Aluminium and zinc in USD per metric ton
curl "https://metalapi.com/api/v1/latest?currencies=ALU,ZNC&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Hot-rolled coil steel in USD per short ton
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Если используется единица не по умолчанию, ответ сообщает об этом в поле unit. Нужная вам цена — ключ с префиксом базовой валюты (USDXCU); ключ XCU без префикса — обратная величина, сохранённая для совместимости со старыми интеграциями:

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

Цены на основе фьючерсов и что такое ближайший месяц

Спотовое золото круглосуточно торгуется на внебиржевом рынке, а промышленные металлы и энергоносители прозрачнее всего оцениваются на фьючерсных биржах. MetalAPI берёт эти цены с COMEX и NYMEX (обе входят в CME Group) и с ICE. Фьючерсный контракт — это стандартизированное соглашение купить или продать определённое количество по определённой цене с поставкой в конкретном месяце. Каждый месяц поставки — отдельный контракт со своей ценой.

Ближайший месяц (front month) — это ближайший месяц поставки, контракт на который ещё торгуется. Непрерывный ряд ближайшего месяца следует за этим контрактом, пока не приблизится его экспирация, а затем переключается, или переходит (roll), на следующий. Для разработчиков важны три следствия:

• Скачки при переходе. В дату перехода ряд может скачкообразно измениться — не потому, что сдвинулся рынок, а потому, что следующий контракт торгуется по другой цене. Когда более дальние месяцы дороже (контанго), ряд делает шаг вверх; когда дешевле (бэквордация) — шаг вниз. Помните об этом, прежде чем настраивать оповещение на однодневное изменение вблизи экспирации.
• Одна биржа — это ещё не весь рынок. Цена меди на COMEX — это цена американской биржи. Значительная часть физической меди, алюминия и цинка в мире оценивается по Лондонской бирже металлов (LME), а физические поставки добавляют региональные премии, фрахт и налоги. Цены на разных площадках тесно связаны, но не совпадают в точности. Если в договоре поставки указан конкретный ориентир, например официальная цена LME или публикуемая ценовая оценка, именно он определяет сумму в вашем счёте. Биржевой поток фьючерсных цен — хороший инструмент для мониторинга и оценки, но не замена договорному индексу.
• Часы торгов. Эти контракты следуют часам работы своих бирж: почти круглосуточно с вечера воскресенья до второй половины дня пятницы по нью-йоркскому времени, с коротким ежедневным перерывом. В выходные MetalAPI продолжает возвращать последнюю цену.

Поскольку эти символы основаны на фьючерсах, они публикуются одной ценой; суффиксы bid и ask для них недоступны. Дневная история металлов и энергоносителей начинается с 2000 года, а в руководстве по историческим данным показано, как запрашивать цены закрытия, диапазоны и бары OHLC.

Пересчёт единиц и валют

Если вам нужны несколько металлов в разных единицах, дешевле всего сделать один запрос в тройских унциях и выполнить пересчёт в собственном коде. Запрос данных учитывается один раз, сколько бы символов он ни вернул, поэтому так вы потратите один запрос вместо трёх. Константы ниже следуют из определений единиц:

// Troy ounces in one unit of mass
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 per troy ounce
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

Для металлов и энергоносителей валюты работают одинаково. Добавьте base=EUR или любую из 57 поддерживаемых валют, и все цены в ответе будут выражены в этой валюте с пересчётом по одному и тому же снимку. Чтобы сразу оценить определённое количество, используйте /convert — он принимает количество и единицу:

# 25 metric tons of copper in euros
curl "https://metalapi.com/api/v1/convert?from=XCU&to=EUR&amount=25&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

Пересчёт для энергоносителей выполняется в вашем коде. Полезные стандартные коэффициенты: один баррель — это 42 галлона США, или около 158,987 литра; один галлон США — 3,785411784 литра; один MMBtu — около 1,055 гигаджоуля, 293,07 кВт·ч или 10 термов. Пересчёт баррелей сырой нефти в тонны зависит от плотности нефти, поэтому используйте коэффициент для того сорта, который вы фактически закупаете.

Сценарий: закупки и мониторинг затрат

Отделы закупок используют биржевые цены, чтобы понимать, куда движутся затраты на сырьё, и проверять предложения поставщиков на адекватность. Типичные составляющие:

• Ежедневный дашборд с ценами на медь, алюминий, сталь и дизельное топливо в тех единицах и валюте, которые используются в ваших договорах.
• Изменение за период с помощью /change: он одним запросом возвращает для каждого символа начальную цену, конечную цену, абсолютное и процентное изменение между двумя датами.
• Пороговые оповещения. На платных тарифах ценовые оповещения в личном кабинете отправляют письмо, а начиная с тарифа Advanced — и подписанный вебхук, когда цена пересекает заданный уровень или изменяется на заданный процент. Это простой способ запустить пересмотр бюджетных допущений.
• Проверка предложений. Сравнение стоимости металла в цене поставщика с биржевым ориентиром показывает, какая часть изменения цены связана с металлом, а какая — с премиями или переработкой.

# Copper and aluminium per metric ton: change over September 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"

Помните об оговорке выше: если договор привязан к конкретной публикуемой цене, сверяйтесь с этим индексом во всём, что попадает в счёт.

Сценарий: модели себестоимости в производстве

В спецификации материалов (BOM) содержание металла обычно указывается в килограммах. Поскольку unit принимает kilogram для любого металла, один запрос возвращает цену за килограмм для всех металлов сразу в вашей валюте отчётности:

import os
import requests

# Metal content per unit of product, in kg (illustrative)
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']})")

Два улучшения делают такую модель полезнее. Во-первых, сохраняйте рядом с каждым расчётом затрат использованные цену, единицу и метку времени, чтобы потом можно было объяснить, почему изменилась себестоимость. Во-вторых, подумайте о средней цене за период вместо одной последней цены: она сглаживает дневной шум и скачки при переходе контрактов. На платных тарифах /timeframe возвращает дневные цены закрытия за период до 365 дней на запрос (на Free — до 30 дней), чего достаточно для месячного или квартального среднего за один вызов.

Сценарий: логистика и затраты на топливо

Топливо — крупнейшая переменная статья затрат для многих перевозчиков, а топливные надбавки часто пересчитываются еженедельно или ежемесячно. HEATINGOIL — контракт на дизельное топливо со сверхнизким содержанием серы NY Harbor — широко используемый оптовый ориентир для дизеля. GASOLINE (RBOB) играет ту же роль для бензина, а WTI и BRENT охватывают сырую нефть.

Оптовые фьючерсы и цены на АЗС — разные вещи: розничные цены включают расходы на дистрибуцию, маржу и налоги и следуют за фьючерсами с запаздыванием. Многие графики топливных надбавок ссылаются на публикуемую среднюю розничную цену, и если ваш график тоже, использовать нужно именно её. Тем не менее данные фьючерсов полезны для внутреннего учёта затрат и для того, чтобы заранее видеть изменения выше по цепочке поставок.

Этот пример усредняет дневные цены закрытия контракта на дизельное топливо за прошлую неделю и пересчитывает результат из долларов США за галлон в евро за литр:

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 is keyed by date; days without a close (weekends, holidays) are missing
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");

Практические советы

• Опрашивайте API с интервалом вашего тарифа, не чаще. На Free цены обновляются раз в день, на Lite — каждые 30 минут, на Standard — каждые 10 минут, на Advanced и Pro — каждую минуту, на Ultra и Business — каждые 15 секунд, а на Enterprise — каждые 5 секунд. Запросы в промежутках возвращают тот же снимок, но всё равно учитываются. Начиная с Pro вместо опроса можно использовать поток в реальном времени.
• Объединяйте символы. Один запрос может вернуть все девять символов промышленных металлов и энергоносителей и стоит столько же, сколько запрос одного символа.
• Сохраняйте полученные данные. Храните каждую цену вместе с символом, единицей, базовой валютой и timestamp. Пересчитать позже легко, а угадать единицу старого числа — нет.
• Ожидайте пропусков в истории. В дневных рядах нет выходных и биржевых праздников, поэтому не рассчитывайте на одну запись на каждый календарный день.
• Разбивайте длинные диапазоны. Один запрос /timeframe на платных тарифах охватывает до 365 дней, поэтому для более длинной истории, вплоть до 2000 года, загружайте данные в цикле по годам.
• Проверяйте параметры перед отправкой. Запросы, отклонённые из-за некорректных дат, символов или единиц, всё равно расходуют квоту, поэтому сначала проверяйте их в своём коде. Отказы из-за лимита запросов и ошибки сервера не тарифицируются.

Чтобы начать, зарегистрируйтесь и получите бесплатный ключ, посмотрите текущие цены на промышленные металлы и энергоносители на странице символов и изучите все эндпоинты и параметры в документации API. На странице тарифов указаны интервал обновления и квота каждого тарифа.