Форматы данных и единицы измерения

Два направления для каждого курса

Для каждого запрошенного символа rates содержит два числа. Для золота (XAU) с базовой валютой USD:

• USDXAU: цена одной тройской унции золота в долларах США, например 3997.89. Именно это число стоит показывать пользователям.
• XAU: обратная величина — количество тройских унций золота за один доллар США, например 0.0002501319446. Этот формат сохранён для совместимости с API в стиле форекс.

Для валют действует то же правило. При базовой валюте USD значение USDEUR — это цена одного евро в долларах, а EUR — количество евро за один доллар.

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "EUR": 0.8589589418,
    "USDEUR": 1.1642
  }
}

Выбор базовой валюты

base задаёт валюту всех цен в ответе. По умолчанию это USD, но подходит любой поддерживаемый символ: EUR, GBP, JPY и даже BTC или XAU, если вы хотите выражать стоимость в биткоинах или золоте. Кросс-курсы рассчитываются по одному и тому же срезу данных, поэтому всегда согласованы между собой.

Этот запрос возвращает EURXAU — цену золота в евро за тройскую унцию:

GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR&currencies=XAU,XAG

Единицы массы

Цены на металлы указываются за тройскую унцию (31,1035 г), если вы не передали unit. Поддерживаемые значения:

• troy_oz (по умолчанию), gram, kilogram, ounce (торговая унция avoirdupois, 28,35 г), pound, metric_ton и short_ton

Также принимаются краткие формы, например g, kg, lb и tonne. Обратите внимание: oz означает торговую унцию avoirdupois. Чтобы получить тройскую унцию, в которой котируются слитки, используйте troy_oz или не указывайте unit.

unit действует только для драгоценных и промышленных металлов. Энергоносители по-прежнему котируются за баррель, MMBtu или галлон, а на валюты и криптовалюты параметр не влияет. Если используется единица, отличная от единицы по умолчанию, ответ содержит поле unit. Для GET /api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram:

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "EUR",
  "unit": "gram",
  "rates": {
    "XAU": 0.009057444725,
    "EURXAU": 110.4064149,
    "XAG": 0.6713138244,
    "EURXAG": 1.489616277
  }
}

Промышленные металлы и энергоносители

Промышленные металлы (XCU — медь, ALU — алюминий, ZNC — цинк и HRC — горячекатаный стальной прокат в рулонах) по умолчанию котируются за тройскую унцию, как и все остальные металлы, поэтому все металлы можно сравнивать напрямую. Чтобы получить цену в единице, принятой на соответствующем рынке, передайте unit=pound для меди, unit=metric_ton для алюминия и цинка и unit=short_ton для стали.

Цены на энергоносители указываются за единицу контракта: WTI и BRENT — за баррель, NATURALGAS — за MMBtu, GASOLINE и HEATINGOIL — за галлон.

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XCU&unit=pound

Поддерживаемые символы

• Драгоценные металлы: XAU — золото, XAG — серебро, XPT — платина, XPD — палладий
• Промышленные металлы: XCU — медь, ALU — алюминий, ZNC — цинк, HRC — сталь
• Энергоносители: WTI, BRENT, NATURALGAS, GASOLINE, HEATINGOIL
• Валюты: около 55 валют ISO 4217, включая USD, EUR, GBP, JPY, CHF, CAD, AUD, CNY и INR
• Криптовалюты: BTC, ETH, SOL, XRP, BNB, ADA, DOGE, DOT, LINK, LTC, TRX, USDT, USDC

Полный актуальный список есть на странице символов и доступен через /api/v1/symbols.

Цены bid и ask

На тарифе Standard и выше добавьте -BID или -ASK к символу в currencies, чтобы получить цены bid и ask вместе со средней ценой. Они доступны для символов, котировки которых поступают с межбанковского рынка, — драгоценных металлов и основных валют. Для currencies=XAU,XAU-BID,XAU-ASK:

"rates": {
  "XAU": 0.0002501319446,
  "USDXAU": 3997.89,
  "XAU-BID": 0.0002501488386,
  "USDXAU-BID": 3997.62,
  "XAU-ASK": 0.0002501150529,
  "USDXAU-ASK": 3998.16
}

Цены на золото по каратам

/carat возвращает цены на золото ювелирных проб (чистота = караты ÷ 24) в любой валюте и единице измерения. Эндпоинт доступен на платных тарифах. Для GET /api/v1/carat?carat=all&unit=gram (в сокращённом виде):

{
  "success": true,
  "carat": "all",
  "date": "2026-10-23",
  "base": "USD",
  "timestamp": 1792765800,
  "rates": {
    "XAU24K": { "price": 128.53515, "unit": "gram", "carat": "24", "purity": 1 },
    "XAU22K": { "price": 117.82389, "unit": "gram", "carat": "22", "purity": 0.916667 },
    "XAU18K": { "price": 96.401361, "unit": "gram", "carat": "18", "purity": 0.75 },
    "XAU14K": { "price": 74.978836, "unit": "gram", "carat": "14", "purity": 0.583333 }
  }
}

Метки времени и даты

timestamp — время Unix в секундах (UTC), к которому относятся возвращённые цены. date — тот же день в формате YYYY-MM-DD по UTC. Исторические ответы имеют метку 00:00 UTC запрошенного дня и содержат цены закрытия этого дня.

const date = new Date(data.timestamp * 1000);
console.log(date.toISOString()); // 2026-10-23T14:30:00.000Z

Точность

Курсы передаются как числа JSON с точностью до 10 значащих цифр, чего достаточно для обратных курсов вроде 0.0002501319446. Округляйте значения только при отображении, а не перед расчётами.

Часы работы рынков и выходные

Спотовые металлы и валюты торгуются круглосуточно по будним дням. Рынки закрываются в пятницу в 17:00 по нью-йоркскому времени и снова открываются в воскресенье в 17:00. В выходные цены замирают на последней котировке, и API продолжает возвращать цену закрытия пятницы (на страницах символов отображается «Рынок закрыт»).

Криптовалюты торгуются круглосуточно без выходных и продолжают обновляться в субботу и воскресенье. Промышленные металлы и энергоносители следуют часам торгов своих фьючерсных бирж.