API 文档概览
一页速览 MetalAPI REST API：基础 URL、身份验证、请求参数、响应格式、错误代码、速率限制，以及 Node.js、PHP 和 Python 代码示例，助您快速上手贵金属价格接口。
API 参考 阅读约 10 分钟
基础 URL
所有请求都通过 HTTPS 发送到 https://metalapi.com/api/v1/，并使用 GET 方法。响应为 JSON 格式，带有 success 标志。
本页是一份快速概览。包含所有参数的完整参考请参见 API 文档。
身份验证
可以通过查询参数、Bearer 令牌或 X-API-Key 请求头发送 API 密钥。密钥格式为 mk_live_ 后跟 32 个字符。请妥善保密；参见身份验证。
http
# 查询参数
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。
http
GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR¤cies=XAU,XAG,USD,GBP&unit=gram响应格式
成功的响应包含 success: true、数据以及 rate_limit 区块。每个品种都会出现两次：XAU（每单位基础货币可买到的金衡盎司数）和 USDXAU（1 金衡盎司以基础货币计的价格）。参见数据格式与单位。
json
{
"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 正文，其中包含数字代码、类型和消息。完整列表请参见错误处理。
json
{
"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+）：
javascript
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
<?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 库：
python
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 美元换算为黄金（以金衡盎司计）：
bash
curl "https://metalapi.com/api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000"响应示例
result 是换算后的金额，info.rate 是所采用的汇率：
json
{
"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"
}
}相关指南
可用端点MetalAPI 全部端点及参数说明：latest、historical、convert、timeframe、change、OHLC、carat、symbols、usage 和 stream，每个端点均附有请求示例，便于快速查阅与集成。阅读约 9 分钟错误处理MetalAPI 错误代码及其对应的 HTTP 状态码一览，以及如何在代码中处理失败的请求、哪些错误值得重试，如何使用指数退避制定合理的重试策略。阅读约 6 分钟数据格式与单位了解 MetalAPI 价格的两种表示方向、如何选择基础货币和质量单位、买卖价与按成色计的金价、时间戳格式以及市场交易时间，正确解析每一个 API 响应。阅读约 8 分钟
准备好开始构建了吗？
创建免费账户获取 API 密钥，或在 API 参考中浏览所有端点。