黄金API教程

黄金价格 API：开发者完全指南

黄金价格 API 使用指南：获取密钥，用 curl、JavaScript 和 Python 发起调用，正确解读汇率格式，并妥善处理历史数据、错误、配额与缓存。

作者：MetalAPI Team·发布于 2026年10月25日·阅读约 9 分钟

黄金价格 API 能为您提供什么

黄金价格 API 以结构化数据（通常是通过 HTTPS 传输的 JSON）返回黄金的当前价格和历史价格，让您的软件无需抓取网页或手动复制数字即可使用。在 MetalAPI 中，黄金的代码为 XAU，即 ISO 4217 中代表 1 金衡盎司黄金的代码。它的实时价格是现货价：银行间买入价与卖出价报价的中间值。

大多数集成并不是交易系统。典型用途如下：

随行情变动为黄金商品重新定价的网店和珠宝商。
旧金回收、K 金首饰或金条溢价计算器。
以本地货币评估持仓价值的投资组合追踪器和个人理财应用。
按每日收盘价重新评估库存价值的会计和 ERP 系统。
需要展示过去一年走势图的数据看板、新闻简报和内部报表。

同一个 API 还涵盖白银（XAG）、铂金（XPT）和钯金（XPD）、四种工业金属、五种能源合约、57 种货币和 13 种加密货币，共 83 个品种，全部列在品种页面上。本指南以黄金为重点，但其中的所有内容同样适用于其他品种。

获取 API 密钥

创建免费账户。Free 套餐无需信用卡，每月包含 100 次请求，价格每日更新，足以用来构建和测试集成。付费套餐提供更新鲜的价格、更多请求次数和额外的端点，下文的套餐表格对此做了汇总。

在控制台中打开 API keys 并创建一个密钥。密钥以 mk_live_ 开头。由于我们只存储密钥的哈希值，完整密钥仅显示一次，因此请立即将其放入环境变量或密钥管理服务中：

Shell

export METALAPI_KEY="mk_live_your_key_here"

API 接受三种等效的密钥传递方式：api_key 查询参数、Authorization: Bearer 请求头或 X-API-Key 请求头。生产环境中建议使用请求头，因为完整的 URL 往往会出现在访问日志、代理和错误追踪工具中。身份验证指南还介绍了供浏览器调用使用的域名限制密钥。

三种身份验证方式

# 1. 查询参数
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

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

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

用 curl、JavaScript 和 Python 发出第一个请求

所有端点都是 https://metalapi.com/api/v1/ 下的普通 GET 请求。/latest 端点返回当前价格。base 设置价格的计价货币（默认为 USD），currencies 将响应限定为您需要的品种。一次请求可以返回多个品种，但仍只计为一次请求。

curl

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：

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})`);

以及使用 requests 库的 Python 版本：

gold.py

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 中都会出现两次，两个数字互为倒数：

键	含义	示例值
`USDXAU`	1 金衡盎司黄金以基础货币（USD）计的价格	`3997.89`
`XAU`	1 单位基础货币可买到的黄金金衡盎司数	`0.0002501319`

通用规则是：rates.<BASE><SYMBOL> 是 1 单位该品种以基础货币计的价格；不带前缀的 rates.<SYMBOL> 键则是倒数，即 1 单位基础货币可兑换的该品种数量。保留倒数形式是为了兼容外汇类 API 以及较早的 MetalAPI 集成。

黄金价格集成中最常见的错误，是读取 rates.XAU 并把它当作价格。它其实是 1 ÷ 价格，结果商品页面显示 0.00025 而不是 3,997.89，任何乘以它的计算都会相差好几个数量级。请读取带前缀的键，例如 rates.USDXAU 或 rates.EURXAU。

如果您已经存储了旧集成中的倒数值，无需重新下载：价格 = 1 ÷ 倒数。以上面的数据为例，1 ÷ 0.0002501319 得到的仍是 3997.89，只是最后几位因取整略有差异。

货币遵循同样的规则。基础货币为 USD 时，USDEUR 是 1 欧元的美元价格，EUR 是 1 美元可兑换的欧元数。数据格式指南提供了更多示例，包括 Standard 及以上套餐可用的买入价和卖出价键。

基础货币与单位

要以其他货币为黄金计价，请修改 base，汇率的键也会随之变化：base=EUR 返回 EURXAU，base=INR 返回 INRXAU。交叉汇率来自同一快照，因此以欧元计的金价与欧元的美元汇率始终保持一致。

金属价格默认按金衡盎司计。unit 参数可以按其他重量单位返回价格：

unit	计价单位	典型用途
`troy_oz`（默认）	金衡盎司，31.1034768 克	金银条报价
`gram`	克	首饰和零售
`kilogram`	千克	千克金条、批发
`ounce`	常衡盎司，28.349523125 克	很少适用于黄金
`pound`	常衡磅	铜
`metric_ton`	公吨（1,000 千克）	铝、锌
`short_ton`	短吨（2,000 磅）	钢材（HRC）

下面的请求返回以欧元/克计的黄金和白银价格。当 unit 不是默认值时，响应会在顶层的 unit 字段中重复该单位：

bash

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

unit=ounce（及其简写 oz）表示常衡盎司，比金衡盎司轻约 8.9%。如需金银条价格，请省略 unit 或传入 troy_oz。

unit 仅对贵金属和工业金属有效，不会改变能源、货币和加密货币的价格。关于金衡盎司、克、托拉（tola）和取整的详细说明，请阅读金衡盎司、克与千克价格换算。如果您销售首饰，K 金价格详解介绍了 22K 和 18K 金价以及 /carat 端点。

黄金历史价格

过去的价格使用相同的参数和相同的响应格式。金属和能源的历史数据从 2000 年开始，货币从 1999-01-04 开始，加密货币从 2014 年开始。以下四个端点可以满足大多数需求：

/YYYY-MM-DD（或 /historical?date=YYYY-MM-DD，或 /yesterday）：某一天的收盘价。对于周末和节假日，返回最近一个交易日的收盘价。
/timeframe（别名 /timeseries）：start_date 与 end_date 之间的每日收盘价，单次请求最多 30 天（Free）或 365 天（付费套餐）。
/change：两个日期之间的起始价、结束价、绝对变化和百分比变化。
/ohlc：某一天的开盘价、最高价、最低价和收盘价。

bash

# 2024 年 1 月 15 日收盘时的黄金和白银价格
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# 2026 年 9 月以欧元计的每日黄金收盘价
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"
  }
}

最常遇到的错误代码：

代码	类型	HTTP	处理方法
`101`、`102`	`no_api_key`、`invalid_api_key`	401	发送有效的密钥，并检查环境变量
`104`	`too_many_requests`	429	等待 `Retry-After` 指定的秒数后重试
`105`	`quota_exceeded`	429	每月配额已用完，将于每月 1 日（UTC）重置
`106`	`plan_restriction`	403	您的套餐不包含该端点或参数
`205`	`invalid_date`	400	修正格式错误或属于未来的日期
`207`	`timeframe_too_long`	400	将区间拆分为多个更短的请求
`300`	`no_results`	404	没有数据，例如早于历史数据的起始日期
`500`、`503`	`server_error`、`service_unavailable`	500、503	使用指数退避重试

每个经过身份验证的响应都会报告您的配额，既通过 X-RateLimit-* 响应头，也通过响应正文中的 rate_limit 对象。/usage 和 /symbols 从不计入配额，因此监控系统可以随意调用。因 104、106、107 或服务器错误而被拒绝的请求不计费，但校验错误会计费。错误处理指南列出了所有错误代码，并提供了一个重试辅助函数。

各套餐的主要区别在于请求量和价格的新鲜程度：

套餐	月费	每月请求数	更新频率	新增功能
Free	$0	100	每日	30 天区间
Lite	$4.99	1,000	30 分钟	K 金价格、365 天区间
Standard	$11.99	10,000	10 分钟	买入价/卖出价
Advanced	$24.99	50,000	1 分钟	Webhook 提醒
Pro	$49.99	100,000	1 分钟	实时流
Ultra	$99.99	500,000	15 秒	更高请求量
Business	$149.99	500,000	15 秒	可用性 SLA
Enterprise	$299.99	1,500,000	5 秒	最高请求量

按年付费最多可节省 25%。最新详情请以定价页面为准。

缓存与生产环境建议

以高于套餐更新频率的频率请求 /latest，只会返回相同的数字，白白消耗配额。请至少按套餐的更新间隔缓存最新价格，并永久缓存过去日期的数据。下面的 Python 辅助函数会缓存最新价格，并在无法连接 API 时继续提供最后一次成功获取的响应：

cache.py

import os
import time

import requests

TTL_SECONDS = 600  # Standard 套餐：价格每 10 分钟更新一次
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"]  # 最后一次成功获取的价格；请显示其时间戳
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

以下几个习惯能让集成既省钱又可靠：

在一次调用中请求所有品种。currencies=XAU,XAG,XPT,XPD 只需一次请求，分四次调用则需要四次。
将密钥保存在服务器上。如果必须从浏览器调用 API，请使用域名限制密钥。如果想在网站上显示价格而不编写代码，可嵌入小组件可以让密钥完全不出现在页面中。
显示时间戳。timestamp 是数据的时间，而不是您发出请求的时间。请将其显示在价格旁边，尤其是在提供缓存值或周末休市的时候。
规划轮询预算。每 10 分钟轮询一次，每月约消耗 4,500 次请求；每分钟轮询一次，则约消耗 45,000 次。从 Pro 套餐起，您可以改用实时流；从 Advanced 套餐起，您可以接收 Webhook 价格提醒。
设置超时并有选择地重试。将超时设为 10 秒左右；对 104 按 Retry-After 等待后重试，对 5xx 错误使用退避重试；切勿重试校验错误。
提前校验品种代码。在启动时加载一次 /symbols（免费），在未知代码消耗请求之前就将其拒绝。

如果您使用 AI 助手，位于 https://metalapi.com/mcp 的 MetalAPI MCP 服务器以工具的形式提供同样的数据，让 Claude、ChatGPT、Cursor 或 VS Code 能够按您的套餐查询金价和历史数据；参见 AI 与 MCP。所有端点和参数请以 API 文档为准。

用您自己的数据试一试

创建免费账户，两分钟内即可发起第一次请求。每月 100 次请求，无需信用卡。

免费获取 API 密钥阅读文档