贵金属行情 API 接口文档

认证方式 · 调用示例 · 频率限制 · 返回字段 · 错误码 · 品种字典

概述

本平台提供贵金属实时行情查询接口，注册后使用平台签发的 AppKey 调用，单次请求最多可批量获取 50 个品种。

在线试用

还没有密钥？一键领取试用密钥，立刻在浏览器里调一次真实行情：

调用结果将显示在这里…

认证方式

通过平台签发的 AppKey 认证。三种传参方式任选其一：

频率与配额

平台有三条互相独立的调用通道，同一次请求只会走其中一条；具体走哪条由该次请求携带的 goldId 与账户权益共同决定：

一次请求携带多个 goldId 时：全部品种都属于单品通道才按单品通道计量；只要其中有一个不属于， 整次请求按会员/赠送通道计量（避免混合请求绕过配额）。 付费权益优先：已开通的会员与单品先消耗，注册赠送的额度自动保留到最后使用。 特别地，会员有效期内一律走会员通道，赠送额度一分不扣，会在会员到期后自动接着生效 —— 赠送额度不会挤占任何已付费权益。 响应头 X-Billing 会标明本次实际使用的通道（member / variety / gift）。

响应头会返回实时配额，便于客户端自行控制节奏（会员通道示例）：

X-Request-Id: 20260928173620-a1b2c3d4
X-Response-Time: 31ms
X-Billing: member
X-RateLimit-Daily-Limit: 1000
X-RateLimit-Daily-Remaining: 973
X-RateLimit-QPS-Limit: 5
X-Account: huaxin_gold

单品通道的响应头不含日/月配额，只给该通道的限速：

X-Billing: variety
X-RateLimit-Variety-QPS: 1

赠送通道会额外返回剩余免费额度，便于判断何时需要开通会员：

X-Billing: gift
X-RateLimit-Gift-Remaining: 4831
X-RateLimit-QPS-Limit: 1

实时行情

请求参数

请求示例

GET https://www.gold-api.cn/api/v1/gold/realtime?goldid=1061&appkey=你的appkey

GET https://www.gold-api.cn/api/v1/gold/realtime?goldid=1061,1062,hf_GC&appkey=你的appkey

成功响应

{
  "success": "1",
  "result": {
    "dtQuery": "1061,1062",
    "dtCount": "2",
    "dtList": {
      "1061": {
        "goldId": "1061",
        "variety": "Au_Spot",
        "varietyName": "黄金现货",
        "lastPrice": 897.60000,
        "buyPrice": 894.60000,
        "sellPrice": 897.60000,
        "highPrice": 927.82000,
        "lowPrice": 897.03000,
        "openPrice": 0.00000,
        "yesyPrice": 928.50000,
        "changePrice": -30.90000,
        "changeMargin": "-3.33%",
        "updateTime": "2026-09-28 17:33:10"
      },
      "1062": { ... }
    }
  },
  "requestId": "20260928173620-a1b2c3d4"
}

失败响应

{
  "success": "0",
  "msgId": "DAILY_LIMIT_EXCEEDED",
  "msg": "今日调用次数已达上限，请明日再试或提升配额",
  "requestId": "20260928173620-a1b2c3d4"
}

历史行情

小时级 OHLCV 蜡烛数据（时间升序返回），数据自 2026-05-27 起可用。与实时行情同一套鉴权与计费，每次请求计 1 次调用。

请求参数

请求示例

GET https://www.gold-api.cn/api/v1/gold/history?goldid=1061&start_date=2026-10-01&end_date=2026-10-31&appkey=你的appkey

成功响应

{
  "success": "1",
  "result": {
    "goldId": "1061",
    "variety": "Au_Spot",
    "startDate": "2026-10-01",
    "endDate": "2026-10-31",
    "count": "744",
    "data": [
      {
        "timestamp": "2026-10-01 00:00:00",
        "open": 838.50000,
        "high": 840.12000,
        "low": 837.90000,
        "close": 839.81000,
        "volume": 0
      },
      { ... }
    ]
  },
  "requestId": "20261104093000-a1b2c3d4"
}

返回字段

品种列表

获取平台全部可用品种，无需认证，可用于前端下拉框。可选参数 market 按市场筛选。

GET https://www.gold-api.cn/api/v1/gold/varieties

{
  "success": "1",
  "result": {
    "dtCount": "69",
    "dtList": [
      { "goldId": "1061", "name": "黄金现货", "market": "现货", "category": "黄金" },
      ...
    ]
  }
}

错误码

接入示例

curl -s "https://www.gold-api.cn/api/v1/gold/realtime?goldid=1061&appkey=你的appkey"

<?php
$appkey = '你的appkey';
$url = 'https://www.gold-api.cn/api/v1/gold/realtime?goldid=1061,1062&appkey=' . $appkey;

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
]);
$json = curl_exec($ch);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($json, true);
if (($data['success'] ?? '0') !== '1') {
    exit('调用失败：' . ($data['msgId'] ?? '') . ' ' . ($data['msg'] ?? ''));
}

foreach ($data['result']['dtList'] as $gid => $q) {
    printf("%s 最新价 %.2f（%s）\n", $q['varietyName'], $q['lastPrice'], $q['changeMargin']);
}

const APPKEY = "你的appkey";
const url = `https://www.gold-api.cn/api/v1/gold/realtime?goldid=1061&appkey=${APPKEY}`;

const res  = await fetch(url);
const data = await res.json();

if (data.success !== "1") {
  throw new Error(`${data.msgId}: ${data.msg}`);
}
console.log(data.result.dtList["1061"].lastPrice);

// 定时轮询（3 秒一次）
setInterval(async () => {
  const r = await fetch(url).then(r => r.json());
  if (r.success === "1") render(r.result.dtList);
}, 3000);

import requests

APPKEY = "你的appkey"
URL = "https://www.gold-api.cn/api/v1/gold/realtime"

r = requests.get(URL, params={"goldid": "1061,1062", "appkey": APPKEY}, timeout=5)
data = r.json()

if data.get("success") != "1":
    raise RuntimeError(f"{data.get('msgId')}: {data.get('msg')}")

for gid, q in data["result"]["dtList"].items():
    print(q["varietyName"], q["lastPrice"], q["changeMargin"])

HttpClient client = HttpClient.newHttpClient();
String url = "https://www.gold-api.cn/api/v1/gold/realtime?goldid=1061&appkey=你的appkey";

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .timeout(Duration.ofSeconds(5))
    .GET()
    .build();

HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

品种字典

共 70 个品种，按市场分组：

上金所（7）

现货（7）

机构报价（33）

外盘（8）

上期所（6）

广期所（4）

香港（1）

指数（1）

汇率（3）

文档版本 v1.5.39 · 如需新增品种或调整配额，请联系平台管理员。