黄金 API 参考:接口与示例

所有接口都需要 API 密钥:缺少或错误的密钥返回 401,超过限制返回 429。各接口的代码列在下方,全部说明见错误

GETFree /api/v1/price/{symbol}/{currency}/{karat} 金属以某货币计价的价格,按单位和按克。 GETFree /api/v1/karat 一次请求获取所有黄金开数的每克价格。 GETFree /api/v1/convert 在金属、货币和重量单位之间换算。 GETFree /api/v1/symbols 可以请求的金属。 GETFree /api/v1/rates 今日对美元汇率。 GETBasic /api/v1/history/{symbol} 金属在一段时间内的每日收盘价。 GETPro /api/v1/ohlc/{symbol} 每天的开盘、最高、最低和收盘价。

认证

每个请求都需要在此请求头中提供密钥。快速测试时也可用 ?api_key= 发送。密钥只在其账户注册的网站上有效。浏览器可以直接调用 API,但访客会看到密钥。

Header

X-API-Key: YOUR_API_KEY

达到限制时

Free 每小时 100 次请求,Basic 2,000 次,Pro 不限。计数包含账户的所有密钥,也包含因套餐被拒绝的请求,并在每个整点重置。X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset(Unix 时间)请求头显示当前情况;Pro 只返回 X-RateLimit-Limit: unlimited。超过限制会返回 429 和以秒为单位的 Retry-After 请求头。免费套餐限制

实时价格

GET/api/v1/price/{symbol}/{currency}/{karat}API 密钥 · Free 及以上

返回金属以任意货币计价的实时价格,按其单位和按克。黄金可选择 K 数。

路径参数

symbolstring必填: 金属:XAU、XAG、XPT、XPD 或 HG。
currencystring: 货币代码,默认 USD。可用 /rates 中的任意代码。
karatint: 仅黄金:24、22、21、18 或 14,默认 24。会改变每克价格。

查询参数

currencystring: 也可作为查询参数传入相同的值。两者都传时以路径为准。
karatint: 也可作为查询参数传入相同的值。两者都传时以路径为准。

响应字段

price: 每单位价格,不随 K 数变化。埃及镑计价的黄金跟随埃及本地市场。
gram: 每克价格,黄金按响应中的 K 数计算。埃及镑为整数,低于 10 镑时除外。
gramBuy, gramSell: 仅埃及镑计价的黄金:每克的估计买入价和卖出价。
karat: 仅黄金:每克价格的 K 数。
prevClose, chPercent: 仅 Pro:所请求货币的上一收盘价及相对其的涨跌幅(%)。没有收盘价时为 null。
updatedAt: 此响应的时间。

响应代码

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable400 unknown_karat400 karat_only_for_gold404 unknown_symbol429 rate_limit_exceeded

响应结构

{
  "symbol": string,
  "name": string,
  "currency": string,
  "unit": string,        // "oz" | "lb"
  "price": number,
  "gram": number,
  "gramBuy"?: number,    // gold in EGP
  "gramSell"?: number,   // gold in EGP
  "karat"?: number,      // gold
  "prevClose"?: number | null,  // Pro
  "chPercent"?: number | null,  // Pro
  "updatedAt": string    // ISO-8601
}

响应示例

{
    "symbol": "XAU",
    "name": "Gold",
    "currency": "USD",
    "unit": "oz",
    "price": 4072.1,
    "gram": 130.921,
    "karat": 24,
    "updatedAt": "2026-11-07T02:40:58+02:00"
}

各开数价格

GET/api/v1/karatAPI 密钥 · Free 及以上

一次请求返回所有开数(24、22、21、18 和 14)的黄金每克实时价格。只需一种开数时,请使用 /price。

查询参数

currencystring: 货币代码,默认 USD。可用 /rates 中的任意代码。

响应字段

karats[].karat: 开数及其纯度:24 = 100%, 22 = 91.66%, 21 = 87.5%, 18 = 75%, 14 = 58.33%。
karats[].gram: 每克价格,黄金按响应中的 K 数计算。埃及镑为整数,低于 10 镑时除外。
karats[].gramBuy, gramSell: 仅埃及镑计价的黄金:每克的估计买入价和卖出价。
updatedAt: 此响应的时间。

响应代码

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

响应结构

{
  "currency": string,
  "karats": [
    {
      "karat": number,
      "gram": number,
      "gramBuy"?: number,   // EGP
      "gramSell"?: number   // EGP
    }
  ],
  "updatedAt": string    // ISO-8601
}

响应示例

{
    "currency": "USD",
    "karats": [
        {
            "karat": 24,
            "gram": 130.921
        },
        {
            "karat": 22,
            "gram": 120.0022
        },
        {
            "karat": 21,
            "gram": 114.5558
        },
        {
            "karat": 18,
            "gram": 98.1907
        },
        {
            "karat": 14,
            "gram": 76.3662
        }
    ],
    "updatedAt": "2026-11-07T02:40:58+02:00"
}

换算

GET/api/v1/convertAPI 密钥 · Free 及以上

按实时价格在金属与货币、两种金属或两种货币之间换算。黄金可以选择开数。

查询参数

fromstring必填: 换算来源:金属(XAU、XAG、XPT、XPD、HG)或 /rates 中的货币代码。
tostring必填: 换算目标,选项与 from 相同。
amountnumber: 数量,默认为 1,必须大于 0。
unitstring: 金属一侧的单位:gram, tola, oz, tael, kilo, lb。默认使用该金属自身的单位(oz,铜为 lb)。
karatint: 当一侧为黄金时:24, 22, 21, 18, 14。默认为 24。

响应字段

unit: 金属一侧的单位。两侧都是货币时不返回。
karat: 使用的开数。仅当一侧为黄金时返回。
rate: 一个单位的 from 折合多少 to。
result: 数量乘以 rate。
updatedAt: 此响应的时间。

响应代码

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 from_and_to_required400 invalid_amount400 unknown_unit400 unknown_karat400 karat_only_for_gold400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

响应结构

{
  "from": string,
  "to": string,
  "amount": number,
  "unit"?: string,     // metal side
  "karat"?: number,    // gold side
  "rate": number,
  "result": number,
  "updatedAt": string  // ISO-8601
}

响应示例

{
    "from": "XAU",
    "to": "USD",
    "amount": 1,
    "unit": "gram",
    "karat": 24,
    "rate": 130.921,
    "result": 130.92,
    "updatedAt": "2026-11-07T02:40:58+02:00"
}

代码

GET/api/v1/symbolsAPI 密钥 · Free 及以上

返回 API 支持的金属及其名称和单位。

响应字段

symbol: 金属代码。
name: 金属名称。
unit: 价格单位:oz 或 lb。

响应代码

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

响应结构

{
  "symbols": [
    { "symbol": string, "name": string, "unit": string }
  ],
  "_server_time": string  // ISO-8601
}

响应示例

{
    "symbols": [
        {
            "symbol": "XAU",
            "name": "Gold",
            "unit": "oz"
        },
        {
            "symbol": "XAG",
            "name": "Silver",
            "unit": "oz"
        },
        {
            "symbol": "XPT",
            "name": "Platinum",
            "unit": "oz"
        },
        {
            "symbol": "XPD",
            "name": "Palladium",
            "unit": "oz"
        },
        {
            "symbol": "HG",
            "name": "Copper",
            "unit": "lb"
        }
    ],
    "_server_time": "2026-11-07T02:40:58+02:00"
}

汇率

GET/api/v1/ratesAPI 密钥 · Free 及以上

返回今日对美元的汇率,最常用的货币在前。

响应字段

base: 基础货币:USD。
rates: 每种货币对 1 美元的汇率。

响应代码

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

响应结构

{
  "base": "USD",
  "rates": { [currency: string]: number },
  "_server_time": string  // ISO-8601
}

响应示例

{
    "base": "USD",
    "rates": {
        "USD": 1,
        "EUR": 0.89048,
        "GBP": 0.742915,
        "INR": 94.537031,
        "CNY": 6.682525,
        "JPY": 157.835475
    },
    "_server_time": "2026-11-07T02:40:58+02:00"
}

每日历史

GET/api/v1/history/{symbol}API 密钥 · Basic 及以上

金属的每日收盘价,从最早开始,范围以存档为准,最后一行是进行中的今天,因此可能比 days 多一行。每天使用当日汇率,埃及镑计价的黄金还使用当日本地市场溢价。没有已保存汇率的日期会被略去。

路径参数

symbolstring必填: 金属:XAU、XAG、XPT、XPD 或 HG。

查询参数

currencystring: 货币代码,默认 USD。仅限有每日数据的货币,见“货币”一节。
rangestring: 1W、1M、3M、6M、1Y 或 ALL(10 年)。优先于 days,其他值会被忽略。
daysint: 天数,默认 365。限制在 1 到 3650 之间。

响应字段

days: 应用 range 和 1 到 3650 限制后实际使用的天数。
count: 返回的行数。
history[].date, close: 日期及每单位收盘价。今天的收盘价在当天结束前会变化。

响应代码

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_basic404 unknown_symbol429 rate_limit_exceeded

响应结构

{
  "symbol": string,
  "currency": string,
  "days": number,
  "count": number,
  "history": [
    { "date": string, "close": number }  // YYYY-MM-DD, oldest first
  ],
  "_server_time": string  // ISO-8601
}

响应示例

{
    "symbol": "XAU",
    "currency": "USD",
    "days": 1,
    "count": 2,
    "history": [
        {
            "date": "2026-11-06",
            "close": 4072
        },
        {
            "date": "2026-11-07",
            "close": 4072.1001
        }
    ],
    "_server_time": "2026-11-07T02:40:58+02:00"
}

每日 K 线

GET/api/v1/ohlc/{symbol}API 密钥 · Pro 及以上

每天一根 K 线,从最早开始,最后一根是进行中的今天。每天使用当日汇率,埃及镑计价的黄金还使用当日本地市场溢价。没有已保存汇率的日期会被略去。

路径参数

symbolstring必填: 金属:XAU、XAG、XPT、XPD 或 HG。

查询参数

currencystring: 货币代码,默认 USD。仅限有每日数据的货币,见“货币”一节。
startunix: 起始日,Unix 时间(秒)。默认从保存的第一天开始。
endunix: 结束日,Unix 时间(秒)。默认到今天。

响应字段

count: 返回的行数。
candles[].date, open, high, low, close: 日期及每单位价格。
candles[].sealed: 当天已确定时为 true,仍可能变化时为 false。

响应代码

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_pro404 unknown_symbol429 rate_limit_exceeded

响应结构

{
  "symbol": string,
  "currency": string,
  "count": number,
  "candles": [
    {
      "date": string,  // YYYY-MM-DD
      "open": number,
      "high": number,
      "low": number,
      "close": number,
      "sealed": boolean
    }
  ],
  "_server_time": string  // ISO-8601
}

响应示例

{
    "symbol": "XAU",
    "currency": "USD",
    "count": 2,
    "candles": [
        {
            "date": "2026-11-06",
            "open": 4090.3,
            "high": 4106.7998,
            "low": 4032.5,
            "close": 4072,
            "sealed": true
        },
        {
            "date": "2026-11-07",
            "open": 4072.3999,
            "high": 4072.3999,
            "low": 4072.1001,
            "close": 4072.1001,
            "sealed": false
        }
    ],
    "_server_time": "2026-11-07T02:40:58+02:00"
}

货币

/price、/karat、/convert 和 /rates 支持 166 种货币,列表见 /rates。/history 和 /ohlc 支持下方 47 种货币,因为每天都保存当日汇率。在这两个接口使用其他代码会返回 400 unknown_currency。

USDEGPSARAEDKWDQARBHDOMRJODIQDLBPSDGYERLYDTNDDZDMADEURGBPTRYINRIDRCNYVNDPKRJPYCADAUDSGDHKDKRWTHBPHPMXNBRLZARCHFNZDILSMYRPLNCZKSEKNOKDKKHUFRON

错误

错误是带 error 字段的 JSON,部分还会附加表中的字段。请求按以下顺序检查:密钥、每小时限制、套餐、参数。

状态	错误	情况	同时返回
400	`unknown_currency_or_unavailable`	未知货币,或当前无法提供价格	`symbol, currency`
400	`unknown_currency`	在 /history 或 /ohlc 上:没有每日数据的货币	`currency, allowed`
400	`unknown_karat`	K 数不是 24、22、21、18 或 14	`karat, allowed`
400	`karat_only_for_gold`	对非黄金金属指定 K 数	`symbol`
400	`from_and_to_required`	缺少 from 或 to
400	`invalid_amount`	amount 不是大于 0 的数字	`amount`
400	`unknown_unit`	gram, tola, oz, tael, kilo, lb 以外的单位	`unit, allowed`
401	`api_key_required`	请求没有密钥
401	`invalid_api_key`	密钥无效
403	`feature_requires_basic`	套餐不包含此接口
403	`feature_requires_pro`	套餐不包含此接口
403	`key_disabled`	密钥已停用
403	`account_suspended`	账户已被暂停
403	`email_not_verified`	账户邮箱尚未确认
403	`Forbidden`	仅访问 /api 或 /api/v1。其响应使用 status 和 message 字段,而不是 error。
404	`unknown_symbol`	未知金属	`symbol`
404	`not_found`	接口不存在,或路径有多余部分。历史和 K 线接口的 currency 只能作为查询参数。
429	`rate_limit_exceeded`	超过套餐的每小时请求数
503	`prices_unavailable`	金属价格暂时不可用