当前位置：首页 > news >正文

黄金、白银、石油期货市场API对接文档

news 2025/9/30 11:19:17

概述

本文档详细说明如何对接StockTV全球期货API中的黄金、白银和石油期货数据。这些大宗商品期货是全球金融市场的重要组成部分。

认证方式

所有API请求都需要在URL参数中包含API Key：

key=您的API密钥

基础信息

主要期货品种标识符

黄金: XAU (COMEX黄金)
白银: XAG (COMEX白银)
原油: CL (WTI原油), BZ (布伦特原油)

API端点

1. 期货市场列表

获取所有期货品种列表，包括黄金、白银、石油等。

请求示例:

GET https://api.stocktv.top/futures/list?key=您的API密钥

响应示例:

{"code": 200,"message": "操作成功","data": [{"date": "17:57:41","symbol": "XAU","buy": "2385.10","sell": "2385.30","high_price": "2392.60","prev_price": "2378.40","volume": "152306.000","name": "COMEX黄金","time": "2024-08-09","low_price": "2375.20","open_price": "2380.50","last_price": "2385.20","chg": "6.80","chg_pct": "0.29"},{"date": "17:57:56","symbol": "XAG","buy": "28.350","sell": "28.370","high_price": "28.450","prev_price": "28.120","volume": "45218.000","name": "COMEX白银","time": "2024-08-09","low_price": "28.050","open_price": "28.150","last_price": "28.360","chg": "0.240","chg_pct": "0.85"},{"date": "17:58:12","symbol": "CL","buy": "82.45","sell": "82.47","high_price": "83.20","prev_price": "81.80","volume": "285416.000","name": "WTI原油","time": "2024-08-09","low_price": "81.60","open_price": "82.10","last_price": "82.46","chg": "0.66","chg_pct": "0.81"},{"date": "17:58:28","symbol": "BZ","buy": "85.70","sell": "85.72","high_price": "86.40","prev_price": "84.90","volume": "187652.000","name": "布伦特原油","time": "2024-08-09","low_price": "84.70","open_price": "85.20","last_price": "85.71","chg": "0.81","chg_pct": "0.95"}]
}

2. 查询特定期货品种

获取黄金、白银或石油的实时行情数据。

请求示例(黄金):

GET https://api.stocktv.top/futures/querySymbol?key=您的API密钥&symbol=XAU

请求示例(白银):

GET https://api.stocktv.top/futures/querySymbol?key=您的API密钥&symbol=XAG

请求示例(WTI原油):

GET https://api.stocktv.top/futures/querySymbol?key=您的API密钥&symbol=CL

请求示例(布伦特原油):

GET https://api.stocktv.top/futures/querySymbol?key=您的API密钥&symbol=BZ

3. 期货K线数据

获取黄金、白银或石油的历史K线数据。

请求示例(黄金1小时K线):

GET https://api.stocktv.top/futures/kline?key=您的API密钥&symbol=XAU&interval=60

请求示例(原油日K线):

GET https://api.stocktv.top/futures/kline?key=您的API密钥&symbol=CL&interval=1d

时间间隔参数:

1: 1分钟
5: 5分钟
15: 15分钟
30: 30分钟
60: 1小时
1d: 1天

响应示例:

{"code": 200,"message": "操作成功","data": [{"date": "2024-08-09 17:30:00","volume": "1425","high": "2388.40","low": "2385.20","close": "2386.80","open": "2387.50","timestamp": 1723217400.0},{"date": "2024-08-09 17:31:00","volume": "1286","high": "2387.20","low": "2385.80","close": "2386.50","open": "2386.80","timestamp": 1723217460.0}]
}

数据说明

交易时间

黄金(XAU): 几乎24小时交易（芝加哥商品交易所交易时间）
白银(XAG): 几乎24小时交易
原油(CL/BZ): 几乎24小时交易

价格单位

黄金: 美元/盎司
白银: 美元/盎司
原油: 美元/桶

合约规格

黄金: 100金衡盎司/合约
白银: 5000金衡盎司/合约
原油: 1000桶/合约

示例代码

Python示例

import requestsdef get_commodity_futures(symbol):"""获取大宗商品期货数据"""url = "https://api.stocktv.top/futures/querySymbol"params = {"symbol": symbol,"key": "您的API密钥"}response = requests.get(url, params=params)return response.json()# 获取黄金期货数据
gold_data = get_commodity_futures("XAU")
print("黄金价格:", gold_data["data"][0]["last_price"])# 获取白银期货数据  
silver_data = get_commodity_futures("XAG")
print("白银价格:", silver_data["data"][0]["last_price"])# 获取原油期货数据
oil_data = get_commodity_futures("CL")
print("WTI原油价格:", oil_data["data"][0]["last_price"])

JavaScript示例

async function fetchCommodityFutures(symbol) {const response = await fetch(`https://api.stocktv.top/futures/querySymbol?symbol=${symbol}&key=您的API密钥`);const data = await response.json();return data;
}// 获取黄金期货数据
fetchCommodityFutures('XAU').then(data => {console.log('黄金价格:', data.data[0].last_price);
});// 获取原油期货数据
fetchCommodityFutures('CL').then(data => {console.log('WTI原油价格:', data.data[0].last_price);
});

实时数据监控示例

import time
import requestsdef monitor_gold_price(interval=60):"""监控黄金价格变化"""previous_price = Nonewhile True:try:data = get_commodity_futures("XAU")current_price = data["data"][0]["last_price"]if previous_price is not None:change = current_price - previous_pricechange_pct = (change / previous_price) * 100print(f"黄金价格: {current_price} | 变化: {change:+.2f} ({change_pct:+.2f}%)")previous_price = current_pricetime.sleep(interval)except Exception as e:print(f"获取数据失败: {e}")time.sleep(30)# 开始监控黄金价格（每分钟更新）
monitor_gold_price(60)

错误处理

错误代码	说明	处理建议
400	参数错误	检查symbol参数是否正确
401	认证失败	检查API Key是否有效
404	品种不存在	确认期货品种符号正确
500	服务器错误	稍后重试或联系技术支持