可用端点

基础 URL 与通用参数

所有端点都是 https://metalapi.com/api/v1 下的 GET 请求，并且需要 API 密钥（参见身份验证）。大多数端点接受相同的可选参数：

• base：价格的计价货币。默认为 USD，可使用任何支持的品种代码。
• currencies 或其别名 symbols：以逗号分隔的待返回品种列表，例如 XAU,XAG,EUR。省略则返回所有品种。
• unit：金属价格的质量单位。可选 troy_oz（默认）、gram、kilogram、ounce、pound、metric_ton 或 short_ton。

日期采用 YYYY-MM-DD 格式，并按 UTC 解释。

最新价格：/latest

按您套餐的更新间隔返回当前价格，从 Free 的每日更新到 Enterprise 的每 5 秒更新。在 Standard 及以上套餐中，可在 currencies 中添加 XAU-BID 和 XAU-ASK 等代码，以获取买入价和卖出价。

GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY&base=USD&currencies=XAU,XAG,EUR

历史价格：/{date}

返回过去某一天的收盘价。支持三种形式：将日期作为路径、/historical?date= 或 /yesterday。

GET /api/v1/2026-10-01?api_key=YOUR_API_KEY&currencies=XAU,XAG
GET /api/v1/historical?date=2026-10-01&api_key=YOUR_API_KEY&currencies=XAU,XAG
GET /api/v1/yesterday?api_key=YOUR_API_KEY&currencies=XAU,XAG

换算：/convert

将 amount 数量的 from 换算为 to，例如将美元换算为黄金盎司，或将白银换算为欧元。添加 date 可按历史收盘价换算，添加 unit 可换算以克或千克计的金属。

GET /api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000

# 按 2026 年 10 月 1 日收盘价计算 500 克白银值多少欧元
GET /api/v1/convert?api_key=YOUR_API_KEY&from=XAG&to=EUR&amount=500&unit=gram&date=2026-10-01

时间区间：/timeframe

返回 start_date 与 end_date 之间每一天的收盘价。单次请求的跨度在 Free 套餐中最多 30 天，在付费套餐中最多 365 天，超出范围将返回错误 207。/timeseries 是为保持兼容而保留的别名。

GET /api/v1/timeframe?api_key=YOUR_API_KEY&start_date=2026-09-01&end_date=2026-09-30&currencies=XAU

涨跌：/change

返回每个品种在两个日期之间的起始价、结束价、绝对变化和百分比变化，适合用于“本月金价上涨 3.6%”之类的展示。区间限制与 /timeframe 相同。

GET /api/v1/change?api_key=YOUR_API_KEY&start_date=2026-09-30&end_date=2026-10-23&currencies=XAU,XAG

OHLC：/ohlc

返回某一天的开盘价、最高价、最低价和收盘价。省略 date 或传入 latest，即可获取今天截至目前的数据。

GET /api/v1/ohlc?api_key=YOUR_API_KEY&date=2026-10-22&currencies=XAU,XAG

按成色查询金价：/carat

以任意货币和单位返回从 24K 到 8K 各种首饰成色的黄金价格。可传入 carat=24（默认）、单个成色（如 18）或 carat=all。支持的成色为 24、23、22、21、20、18、16、14、12、10、9 和 8K。添加 date 可查询历史成色金价。

此端点仅限付费套餐使用。Free 套餐的密钥会收到错误 106。

GET /api/v1/carat?api_key=YOUR_API_KEY&carat=all&base=EUR&unit=gram

品种列表：/symbols

返回支持的品种代码及其名称。添加 details=1 可包含每个品种的类别和单位。此端点不计入每月配额。

GET /api/v1/symbols?api_key=YOUR_API_KEY&details=1

用量：/usage

返回当前计费月已使用和剩余的请求数。此端点同样免费，因此可以在监控系统中调用而不消耗配额。

GET /api/v1/usage?api_key=YOUR_API_KEY

实时流：/stream

基于 Server-Sent Events 的数据流，在价格变化时即时推送更新，无需轮询 /latest。适用于 Pro 及以上套餐。实时流文档介绍了事件格式。

curl -N "https://metalapi.com/api/v1/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"