金属实时报价接口

概述

实时采集黄金、白银、铂金、钯金等贵金属价格，并以 HTTP API 方式对外提供查询。

接口地址

GET /api/metals/price

请求参数

参数	类型	必填	说明
`code`	string	否	合约代码，不传则返回全部数据

响应字段

字段	类型	说明
`code`	string	合约代码
`name`	string	合约名称
`market`	string	所属市场
`last`	float64	最新成交价
`bid_price`	float64	买一价
`ask_price`	float64	卖一价
`open`	float64	今日开盘价
`high`	float64	今日最高价
`low`	float64	今日最低价
`close`	float64	今日收盘价（盘中为0）
`pre_close`	float64	昨收价
`settle`	float64	结算价
`updown`	float64	涨跌额
`updown_rate`	float64	涨跌幅（小数，如0.012 表示 1.2%）
`volume`	int64	成交量
`updated_at`	string	本地更新时间（ISO 8601）

示例

查询全部价格

GET /api/metals/price

{
  "count": 26,
  "data": [
    {
      "code": "XAU",
      "name": "伦敦金",
      "market": "国际现货",
      "last": 2358.50,
      "bid_price": 2358.30,
      "ask_price": 2358.70,
      "open": 2345.00,
      "high": 2362.10,
      "low": 2340.50,
      "close": 0,
      "pre_close": 2342.00,
      "settle": 0,
      "updown": 16.50,
      "updown_rate": 0.00704,
      "volume": 0,
      "updated_at": "2024-01-15T10:23:45Z"
    }
  ]
}

查询单一合约

GET /api/metals/price?code=Au99.99

{
  "data": {
    "code": "Au99.99",
    "name": "黄金9999",
    "market": "上海黄金交易所",
    "last": 558.50,
    "bid_price": 558.40,
    "ask_price": 558.60,
    ...
  }
}

支持的合约代码

金交所融通金（自营）

代码	说明
`JZJ_au`	黄金综合
`JZJ_au_PS`	黄金卖出价
`JZJ_au_PB`	黄金买入价
`JZJ_ag`	白银综合
`JZJ_ag_PS`	白银卖出价
`JZJ_ag_PB`	白银买入价
`JZJ_pt`	铂金综合
`JZJ_pt_PS`	铂金卖出价
`JZJ_pt_PB`	铂金买入价
`JZJ_pd`	钯金综合
`JZJ_pd_PS`	钯金卖出价
`JZJ_pd_PB`	钯金买入价
`RH_JZL`	铑金综合
`RH_JZL_PS`	铑金卖出价
`RH_JZL_PB`	铑金买入价

上海黄金交易所

代码	说明
`Au99.99`	黄金 9999
`Au(T+D)`	黄金 T+D
`Ag(T+D)`	白银 T+D
`Pt99.95`	铂金 9995

国际现货（美市）

代码	说明
`GLNC`	美黄金
`SLNC`	美白银
`PLNC`	美铂金
`PANC`	美钯金

伦敦现货

代码	说明
`XAU`	伦敦金
`XAG`	伦敦银
`XAP`	伦敦铂
`XPD`	伦敦钯

汇率

代码	说明
`USDCNH`	美元/人民币

错误码

HTTP 状态码	说明
`200`	成功
`404`	指定 code 不存在或尚未收到数据

WebSocket 实时推流

认证

使用 API Key 通过查询参数传递（WebSocket 浏览器客户端无法设置自定义 Header）。

GET /ws/metals/price?token=<api-key>

API Key 通过环境变量 METALS_API_KEY 配置，未设置时默认为 dev-secret-change-me。

消息格式

连接建立后服务端立即推送全量快照，此后每秒推送一次更新：

{
  "type": "snapshot",
  "ts": 1705286625000,
  "data": [
    {
      "code": "XAU",
      "name": "现货黄金",
      "market": "LIFFE",
      "last": 2358.50,
      "bid_price": 2358.30,
      "ask_price": 2358.70,
      ...
    }
  ]
}

字段	说明
`type`	`snapshot`（首帧全量）或 `update`（后续更新）
`ts`	服务端时间戳，Unix 毫秒
`data`	价格数组，字段同 HTTP 接口响应

JavaScript 示例

const ws = new WebSocket('ws://localhost:8080/ws/metals/price?token=dev-secret-change-me');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg.data.length, 'prices, ts=', msg.ts);
};

MCP 接口

遵循 Model Context Protocol 2024-11-05 规范，通过 JSON-RPC 2.0 暴露报价工具，供 AI Agent（如 Claude Desktop）直接调用。

认证

POST /mcp/metals
Authorization: Bearer <api-key>

也支持 X-Api-Key: <api-key> Header。

初始化握手

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0" }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "metals-price", "version": "1.0.0" }
  }
}

可用工具

`tools/list`

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

工具名	说明
`get_metal_price`	查询指定合约代码的实时报价
`list_metal_prices`	返回全部品种实时报价列表

`tools/call` — get_metal_price

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_metal_price",
    "arguments": { "code": "XAU" }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"code\": \"XAU\",\n  \"name\": \"现货黄金\",\n  \"last\": 2358.50,\n  ...\n}"
      }
    ]
  }
}

`tools/call` — list_metal_prices

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_metal_prices",
    "arguments": {}
  }
}

MCP 错误码

JSON-RPC 错误码	说明
`-32700`	JSON 解析失败
`-32601`	方法不存在
`-32602`	参数无效或缺失
HTTP `401`	API Key 认证失败