API цен на золото: полное руководство для разработчиков

Что даёт API цен на золото

API цен на золото возвращает текущую и историческую цену золота в виде структурированных данных, обычно в формате JSON по HTTPS, чтобы ваше ПО могло использовать её без парсинга веб-страниц и ручного копирования чисел. В MetalAPI золото обозначается символом XAU — это код ISO 4217 для одной тройской унции золота. Его текущая цена — спотовая: середина между межбанковскими котировками bid и ask.

Большинство интеграций — это не торговые системы. Типичные сценарии использования:

• Интернет-магазины и ювелиры, которые переоценивают изделия из золота вслед за рынком.
• Калькуляторы для золотого лома, ювелирных изделий по каратам или премий к слиткам.
• Трекеры портфеля и приложения для личных финансов, которые оценивают активы в местной валюте.
• Бухгалтерские и ERP-системы, которые переоценивают запасы по дневной цене закрытия.
• Дашборды, рассылки и внутренние отчёты, которым нужен график за последний год.

Тот же API охватывает серебро (XAG), платину (XPT) и палладий (XPD), четыре промышленных металла, пять энергетических контрактов, 57 валют и 13 криптовалют — всего 83 символа, и все они перечислены на странице символов. Это руководство посвящено золоту, но всё сказанное в нём относится и к остальным символам.

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

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

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

export METALAPI_KEY="mk_live_your_key_here"

API принимает ключ тремя равнозначными способами: в параметре запроса api_key, в заголовке Authorization: Bearer или в заголовке X-API-Key. В продакшене лучше использовать заголовок, потому что полные URL часто попадают в журналы доступа, прокси и системы отслеживания ошибок. В руководстве по аутентификации также описаны ключи с ограничением по доменам для вызовов из браузера.

# 1. Query parameter
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

# 2. Authorization header
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "Authorization: Bearer $METALAPI_KEY"

# 3. X-API-Key header
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

Первый запрос на curl, JavaScript и Python

Каждый эндпоинт — это обычный запрос GET к адресу внутри https://metalapi.com/api/v1/. Эндпоинт /latest возвращает текущие цены. base задаёт валюту, в которой выражены цены (по умолчанию USD), а currencies ограничивает ответ нужными вам символами. Один запрос может вернуть много символов и всё равно считается одним запросом.

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

Успешный ответ выглядит так. Числа — это примерные значения, которые используются во всей документации MetalAPI, а не актуальные цены:

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319,
    "USDXAU": 3997.89,
    "XAG": 0.0185392857,
    "USDXAG": 53.94
  },
  "rate_limit": {
    "limit": 10000,
    "remaining": 9876,
    "reset": 1793491200,
    "used": 124,
    "plan": "Standard",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

Тот же вызов из Node.js 18 или новее, где fetch встроен. Сохраните код как gold.mjs, чтобы работал await верхнего уровня, и запустите node gold.mjs:

const params = new URLSearchParams({ base: "USD", currencies: "XAU,XAG" });
const res = await fetch(`https://metalapi.com/api/v1/latest?${params}`, {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();

if (!data.success) {
  throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
}

const gold = data.rates[`${data.base}XAU`];
const asOf = new Date(data.timestamp * 1000).toISOString();
console.log(`Gold: ${gold} ${data.base} per troy ounce (data from ${asOf})`);

И из Python с библиотекой requests:

import os

import requests

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": "XAU,XAG"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

base = data["base"]
print(f"Gold:   {data['rates'][base + 'XAU']} {base} per troy ounce")
print(f"Silver: {data['rates'][base + 'XAG']} {base} per troy ounce")

Оба фрагмента формируют ключ курса из data.base, а не прописывают его жёстко. Эта маленькая привычка сохраняет код корректным, если позже вы смените базовую валюту, и подводит нас к самой важной части руководства.

Правильно читайте формат курсов

Каждый символ встречается в rates дважды, и эти два числа обратны друг другу:

Общее правило: rates.<BASE><SYMBOL> — цена одной единицы символа в базовой валюте. Ключ без префикса rates.<SYMBOL> — обратная величина: количество единиц символа на одну единицу базовой валюты. Обратная форма сохранена для совместимости с API в стиле форекс и со старыми интеграциями MetalAPI.

Если вы уже храните обратные значения из старой интеграции, загружать их заново не нужно: цена = 1 ÷ обратная величина. В примере выше 1 ÷ 0,0002501319 снова даёт 3 997,89 — с точностью до последних знаков округления.

Валюты подчиняются тому же правилу. При базе USD ключ USDEUR — цена одного евро в долларах, а EUR — количество евро за один доллар. В руководстве по форматам данных есть больше примеров, включая ключи bid и ask, доступные на тарифе Standard и выше.

Базовые валюты и единицы измерения

Чтобы получить цену золота в другой валюте, измените base. Ключ курса меняется вместе с ней: base=EUR возвращает EURXAU, а base=INR — INRXAU. Кросс-курсы берутся из одного снимка, поэтому цена золота в евро и курс евро к доллару всегда согласованы между собой.

По умолчанию цены металлов указываются за тройскую унцию. Параметр unit возвращает их за другую единицу массы:

Этот запрос возвращает цены золота и серебра в евро за грамм. Если unit отличается от значения по умолчанию, ответ повторяет его в поле unit верхнего уровня:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

unit влияет только на драгоценные и промышленные металлы. На энергоносители, валюты и криптовалюты он не действует. Подробнее о тройских унциях, граммах, тола и округлении читайте в статье «Тройские унции, граммы и килограммы». Если вы продаёте ювелирные изделия, статья «Цены на золото по каратам» рассказывает о ценах 22K и 18K и эндпоинте /carat.

Исторические цены на золото

Для прошлых цен используются те же параметры и тот же формат ответа. История начинается с 2000 года для металлов и энергоносителей, с 4 января 1999 года для валют и с 2014 года для криптовалют. Четыре эндпоинта закрывают большинство задач:

• /YYYY-MM-DD (или /historical?date=YYYY-MM-DD, или /yesterday): цены закрытия за один день. Для выходных и праздников возвращается цена закрытия последнего торгового дня.
• /timeframe (псевдоним /timeseries): дневные цены закрытия между start_date и end_date — до 30 дней на запрос на Free и до 365 дней на платных тарифах.
• /change: начальный курс, конечный курс, абсолютное и процентное изменение между двумя датами.
• /ohlc: цены открытия, максимума, минимума и закрытия за один день.

# Gold and silver at the close of 15 January 2024
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Daily gold closes in euros for September 2026
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

Цены закрытия прошедших дней не меняются, поэтому сохраните их один раз, а не запрашивайте повторно. В статье «Исторические цены на золото и серебро через API» разобрано, как загрузить 25 лет данных по частям, сохранить их локально и построить графики. В руководстве по историческим данным есть вспомогательная функция на JavaScript для длинных диапазонов.

Ошибки, квоты и ограничения тарифов

Неудачный запрос возвращает HTTP-статус ошибки и тело с success: false. Объект error содержит числовой code, машиночитаемый type и понятное человеку описание info. Ветвите логику по code или type, но никогда — по тексту info. Ошибки лимита запросов (104), квоты (105), ограничения тарифа (106) и диапазона (207) также содержат upgrade_url:

{
  "success": false,
  "error": {
    "code": 106,
    "type": "plan_restriction",
    "info": "The carat endpoint requires a paid subscription plan",
    "upgrade_url": "https://metalapi.com/dashboard/billing"
  }
}

Коды, с которыми вы, скорее всего, столкнётесь:

Каждый аутентифицированный ответ сообщает состояние квоты — и в заголовках X-RateLimit-*, и в объекте rate_limit в теле. /usage и /symbols никогда не расходуют квоту, поэтому системы мониторинга могут вызывать их свободно. Запросы, отклонённые с ошибками 104, 106, 107 или с ошибкой сервера, не тарифицируются, а ошибки валидации — тарифицируются. В руководстве по обработке ошибок перечислены все коды и есть вспомогательная функция для повторных попыток.

Тарифы различаются в основном объёмом запросов и свежестью цен:

При оплате за год экономия составляет до 25%. Актуальные условия всегда есть на странице тарифов.

Кэширование и советы для продакшена

Если запрашивать /latest чаще, чем обновляются цены на вашем тарифе, вы получите те же числа и впустую потратите квоту. Кэшируйте последние цены как минимум на интервал обновления вашего тарифа, а цены прошедших дней — навсегда. Эта вспомогательная функция на Python кэширует последние цены и продолжает отдавать последний удачный ответ, если API недоступен:

import os
import time

import requests

TTL_SECONDS = 600  # Standard plan: prices update every 10 minutes
session = requests.Session()
session.headers["X-API-Key"] = os.environ["METALAPI_KEY"]
_cache = {"at": 0.0, "data": None}


def latest_prices():
    now = time.monotonic()
    if _cache["data"] and now - _cache["at"] < TTL_SECONDS:
        return _cache["data"]
    try:
        r = session.get(
            "https://metalapi.com/api/v1/latest",
            params={"currencies": "XAU,XAG,XPT,XPD"},
            timeout=10,
        )
        data = r.json()
    except (requests.RequestException, ValueError):
        data = None
    if data and data.get("success"):
        _cache.update(at=now, data=data)
        return data
    if _cache["data"]:
        return _cache["data"]  # last good prices; show their timestamp
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

Ещё несколько привычек, которые делают интеграцию дешёвой и надёжной:

• Запрашивайте все символы одним вызовом. currencies=XAU,XAG,XPT,XPD стоит одного запроса, а четыре отдельных вызова — четырёх.
• Храните ключ на сервере. Если API нужно вызывать из браузера, используйте ключ с ограничением по доменам. Чтобы показывать цены на сайте без написания кода, используйте встраиваемый виджет — тогда ключа на странице не будет вовсе.
• Показывайте метку времени. timestamp — это время данных, а не вашего запроса. Отображайте его рядом с ценой, особенно когда отдаёте закэшированное значение или рынок закрыт на выходные.
• Планируйте бюджет опроса. Опрос каждые 10 минут расходует около 4 500 запросов в месяц, а опрос каждую минуту — около 45 000. Начиная с тарифа Pro вместо этого можно использовать поток в реальном времени, а начиная с Advanced — получать ценовые оповещения через вебхуки.
• Используйте тайм-ауты и выборочные повторы. Установите тайм-аут около 10 секунд, повторяйте запрос после ошибки 104 по истечении Retry-After, а после ошибок 5xx — с нарастающей задержкой, и никогда не повторяйте запросы с ошибками валидации.
• Проверяйте символы заранее. Загрузите /symbols один раз при запуске (это бесплатно) и отклоняйте неизвестные коды до того, как они потратят запрос.

Если вы работаете с ИИ-ассистентами, MCP-сервер MetalAPI по адресу https://metalapi.com/mcp предоставляет те же данные в виде инструментов, так что Claude, ChatGPT, Cursor или VS Code могут узнавать цены на золото и их историю в рамках вашего тарифа; подробнее — в разделе ИИ и MCP. Справочником по всем эндпоинтам и параметрам служит документация API.