Начало работы с MetalAPI

Введение

MetalAPI — это JSON REST API с ценами спот на драгоценные и промышленные металлы, энергоносители, около 55 валют и 13 криптовалют. API отдаёт котировки в реальном времени, дневную историю с 1999 года, конвертацию, бары OHLC и цены на золото по каратам.

Каждый эндпоинт — это обычный HTTPS-запрос GET к https://metalapi.com/api/v1, поэтому API работает с любым языком программирования и любым HTTP-клиентом. Это руководство за несколько минут проведёт вас от регистрации до первого ответа.

Получите ключ API

Создайте бесплатный аккаунт, указав адрес электронной почты. Банковская карта не нужна. Тариф Free включает 100 запросов в месяц с ежедневным обновлением цен — этого достаточно, чтобы опробовать API.

Откройте раздел API keys в личном кабинете и создайте ключ. Ключи начинаются с mk_live_, за которым следуют 32 символа. Мы храним только хеш каждого ключа, поэтому полный ключ показывается один раз. Сразу сохраните его в менеджере паролей или в переменных окружения.

Отправьте первый запрос

Запросите последние цены на четыре драгоценных металла в долларах США. Замените YOUR_API_KEY своим ключом:

curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY&base=USD&currencies=XAU,XAG,XPT,XPD"

Разберитесь в ответе

base — валюта, в которой выражены цены (по умолчанию USD). currencies ограничивает ответ нужными вам символами. Если не указывать этот параметр, в одном ответе придут все символы. Успешный вызов возвращает JSON такого вида:

{
  "success": true,
  "timestamp": 1792713600,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "XAG": 0.01853911754,
    "USDXAG": 53.94,
    "XPT": 0.000620212733,
    "USDXPT": 1612.35,
    "XPD": 0.0006775985906,
    "USDXPD": 1475.8
  },
  "rate_limit": {
    "limit": 100,
    "remaining": 99,
    "reset": 1793491200,
    "used": 1,
    "plan": "Free",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

Каждый символ встречается дважды. USDXAU — цена одной тройской унции золота в базовой валюте; обычно именно это число и нужно показывать. XAU — обратная величина: сколько тройских унций можно купить на один доллар США. Оба направления подробно описаны в руководстве по форматам данных.

Блок rate_limit, который также передаётся в заголовках X-RateLimit-*, показывает, сколько осталось от месячной квоты и когда она обновится.

Вызов из кода

Вот тот же запрос на JavaScript (Node.js 18+, Deno или Bun). На этот раз ключ передаётся не в URL, а в заголовке:

const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
});
const data = await res.json();

if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
console.log("Gold, USD per troy ounce:", data.rates.USDXAU);

Что дальше

• Аутентификация: передача ключа в заголовках и ключи с ограничением по доменам для работы из браузера.
• Доступные эндпоинты: исторические курсы, конвертация, временные ряды, OHLC и цены по каратам.
• Лимиты запросов и тарифы: квоты, поминутные лимиты и интервалы обновления.
• Обработка ошибок: коды ошибок и разумная стратегия повторных попыток.