Обзор документации API
Краткий обзор REST API MetalAPI на одной странице: базовый URL, аутентификация, параметры, формат ответа, ошибки, лимиты запросов и примеры кода.
Базовый URL
Все запросы отправляются на https://metalapi.com/api/v1/ по HTTPS методом GET. Ответы приходят в формате JSON с флагом success.
Эта страница — краткий обзор. Полный справочник со всеми параметрами находится в документации API.
Аутентификация
Передавайте ключ API в параметре запроса, как Bearer-токен или в заголовке X-API-Key. Ключи имеют вид mk_live_ и 32 символа после него. Храните их в секрете; подробнее — в руководстве Аутентификация.
# Параметр запроса
GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY
# Заголовок Authorization
GET https://metalapi.com/api/v1/latest
Authorization: Bearer YOUR_API_KEY
# Заголовок X-API-Key
GET https://metalapi.com/api/v1/latest
X-API-Key: YOUR_API_KEYЭндпоинты
/latest: текущие цены/{YYYY-MM-DD},/yesterdayили/historical?date=: цены закрытия за прошедший день/convert?from=&to=&amount=: конвертация любой суммы, при необходимости — на прошедшую датуdate/timeframe?start_date=&end_date=(псевдоним/timeseries): дневные цены за период/change?start_date=&end_date=: изменение между двумя днями/ohlc?date=: цена открытия, максимум, минимум и цена закрытия за день/carat?carat=24илиcarat=all: цены на золото по каратам (платные тарифы)/symbols: поддерживаемые символы (бесплатно, не расходует квоту)/usage: ваша квота (бесплатно, не расходует квоту)/stream: Server-Sent Events в реальном времени (тариф Pro и выше)
Параметры и примеры для каждого эндпоинта — в руководстве Доступные эндпоинты.
Параметры запроса
api_key: ваш ключ, если вы не передаёте его в заголовкеbase: валюта возвращаемых цен, по умолчаниюUSDcurrenciesилиsymbols: возвращаемые символы через запятую. По умолчанию — все символы.unit: единица массы для металлов. Одно из значений:troy_oz(по умолчанию),gram,kilogram,ounce,pound,metric_tonилиshort_ton.
GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR¤cies=XAU,XAG,USD,GBP&unit=gramФормат ответа
Успешные ответы содержат success: true, данные и блок rate_limit. Каждый символ встречается дважды: XAU (тройские унции за одну единицу базовой валюты) и USDXAU (цена одной тройской унции в базовой валюте). Подробнее — в руководстве Форматы данных и единицы измерения.
{
"success": true,
"timestamp": 1792765800,
"date": "2026-10-23",
"base": "USD",
"rates": {
"EUR": 0.8589589418,
"USDEUR": 1.1642,
"XAG": 0.01853911754,
"USDXAG": 53.94,
"XAU": 0.0002501319446,
"USDXAU": 3997.89
},
"rate_limit": {
"limit": 10000,
"remaining": 9876,
"reset": 1793491200,
"used": 124,
"plan": "Standard",
"reset_date": "2026-11-01T00:00:00.000Z"
}
}Ошибки
При ошибке возвращается HTTP-статус ошибки и тело с success: false, содержащее числовой код, тип и сообщение. Полный список — в руководстве Обработка ошибок.
{
"success": false,
"error": {
"code": 102,
"type": "invalid_api_key",
"info": "User did not supply an access key or supplied an invalid access key"
}
}Ограничение частоты запросов
У каждого тарифа есть месячная квота, которая обнуляется 1-го числа в 00:00 UTC, и поминутный лимит. Каждый аутентифицированный ответ содержит:
X-RateLimit-Limit,X-RateLimit-RemainingиX-RateLimit-Usedдля месячной квотыX-RateLimit-ResetиX-RateLimit-Reset-Date— момент обнуления квотыX-RateLimit-Planс названием вашего тарифаX-RateLimit-Minute-LimitиX-RateLimit-Minute-Remainingдля поминутного лимита
Те же значения есть в блоке JSON rate_limit. Подробнее — в руководстве Лимиты запросов и тарифы.
Поддерживаемые символы
- Драгоценные металлы:
XAU,XAG,XPT,XPD - Промышленные металлы:
XCU,ALU,ZNC,HRC - Энергоносители:
WTI,BRENT,NATURALGAS,GASOLINE,HEATINGOIL - Валюты: около 55, включая
USD,EUR,GBP,JPY,CHF,CAD,AUDиCNY - Криптовалюты: 13 монет, включая
BTC,ETH,SOL,USDTиUSDC
Полный список — на странице символов.
Пример на Node.js
С использованием встроенного fetch (Node.js 18+):
const API_KEY = process.env.METALAPI_KEY;
const BASE_URL = "https://metalapi.com/api/v1";
async function getLatestRates(currencies = "XAU,XAG,EUR") {
const res = await fetch(`${BASE_URL}/latest?currencies=${currencies}`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
return data.rates;
}
const rates = await getLatestRates();
console.log("Gold (USD/oz):", rates.USDXAU);
console.log("Silver (USD/oz):", rates.USDXAG);Пример на PHP
На PHP с использованием cURL:
<?php
$apiKey = getenv('METALAPI_KEY');
$curl = curl_init('https://metalapi.com/api/v1/latest?currencies=XAU,XAG');
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ["X-API-Key: {$apiKey}"],
]);
$response = curl_exec($curl);
$error = curl_error($curl);
curl_close($curl);
if ($error) {
exit("cURL error: {$error}\n");
}
$data = json_decode($response, true);
if (!$data['success']) {
exit("API error {$data['error']['code']}: {$data['error']['info']}\n");
}
echo "Gold (USD/oz): " . $data['rates']['USDXAU'] . "\n";
echo "Silver (USD/oz): " . $data['rates']['USDXAG'] . "\n";Пример на Python
С использованием библиотеки requests:
import os
import requests
API_KEY = os.environ["METALAPI_KEY"]
BASE_URL = "https://metalapi.com/api/v1"
def get_metal_rates(currencies="XAU,XAG,XPT"):
"""Получает последние цены на металлы из MetalAPI."""
response = requests.get(
f"{BASE_URL}/latest",
params={"currencies": currencies},
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = response.json()
if not data["success"]:
raise RuntimeError(f"{data['error']['code']}: {data['error']['info']}")
return data["rates"]
rates = get_metal_rates()
print(f"Gold: {rates['USDXAU']} USD/oz")
print(f"Silver: {rates['USDXAG']} USD/oz")
print(f"Platinum: {rates['USDXPT']} USD/oz")Пример запроса
Конвертация 1 000 долларов США в тройские унции золота:
curl "https://metalapi.com/api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000"Пример ответа
result — сконвертированная сумма, а info.rate — применённый курс:
{
"success": true,
"query": { "from": "USD", "to": "XAU", "amount": 1000 },
"info": { "timestamp": 1792765800, "rate": 0.0002501319446, "quote": 0.0002501319446 },
"date": "2026-10-23",
"result": 0.2501319446,
"rate_limit": {
"limit": 10000,
"remaining": 9876,
"reset": 1793491200,
"used": 124,
"plan": "Standard",
"reset_date": "2026-11-01T00:00:00.000Z"
}
}Похожие руководства
Готовы начать разработку?
Создайте бесплатный аккаунт, чтобы получить ключ API, или изучите все эндпоинты в справочнике API.