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

概述

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

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

1. key=您的API密钥

复制代码

基础信息

主要期货品种标识符

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

API端点

1. 期货市场列表

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

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

复制代码

响应示例:

1. {
2.   "code": 200,
3.   "message": "操作成功",
4.   "data": [
5.     {
6.       "date": "17:57:41",
7.       "symbol": "XAU",
8.       "buy": "2385.10",
9.       "sell": "2385.30",
10.       "high_price": "2392.60",
11.       "prev_price": "2378.40",
12.       "volume": "152306.000",
13.       "name": "COMEX黄金",
14.       "time": "2024-08-09",
15.       "low_price": "2375.20",
16.       "open_price": "2380.50",
17.       "last_price": "2385.20",
18.       "chg": "6.80",
19.       "chg_pct": "0.29"
20.     },
21.     {
22.       "date": "17:57:56",
23.       "symbol": "XAG",
24.       "buy": "28.350",
25.       "sell": "28.370",
26.       "high_price": "28.450",
27.       "prev_price": "28.120",
28.       "volume": "45218.000",
29.       "name": "COMEX白银",
30.       "time": "2024-08-09",
31.       "low_price": "28.050",
32.       "open_price": "28.150",
33.       "last_price": "28.360",
34.       "chg": "0.240",
35.       "chg_pct": "0.85"
36.     },
37.     {
38.       "date": "17:58:12",
39.       "symbol": "CL",
40.       "buy": "82.45",
41.       "sell": "82.47",
42.       "high_price": "83.20",
43.       "prev_price": "81.80",
44.       "volume": "285416.000",
45.       "name": "WTI原油",
46.       "time": "2024-08-09",
47.       "low_price": "81.60",
48.       "open_price": "82.10",
49.       "last_price": "82.46",
50.       "chg": "0.66",
51.       "chg_pct": "0.81"
52.     },
53.     {
54.       "date": "17:58:28",
55.       "symbol": "BZ",
56.       "buy": "85.70",
57.       "sell": "85.72",
58.       "high_price": "86.40",
59.       "prev_price": "84.90",
60.       "volume": "187652.000",
61.       "name": "布伦特原油",
62.       "time": "2024-08-09",
63.       "low_price": "84.70",
64.       "open_price": "85.20",
65.       "last_price": "85.71",
66.       "chg": "0.81",
67.       "chg_pct": "0.95"
68.     }
69.   ]
70. }

复制代码

2. 查询特定期货品种

获取黄金、白银或石油的实时行情数据。
请求示例(黄金):

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

复制代码

请求示例(白银):

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

复制代码

请求示例(WTI原油):

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

复制代码

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

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

复制代码

3. 期货K线数据

获取黄金、白银或石油的历史K线数据。
请求示例(黄金1小时K线):

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

复制代码

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

1. 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天
  

响应示例:

1. {
2.   "code": 200,
3.   "message": "操作成功",
4.   "data": [
5.     {
6.       "date": "2024-08-09 17:30:00",
7.       "volume": "1425",
8.       "high": "2388.40",
9.       "low": "2385.20",
10.       "close": "2386.80",
11.       "open": "2387.50",
12.       "timestamp": 1723217400.0
13.     },
14.     {
15.       "date": "2024-08-09 17:31:00",
16.       "volume": "1286",
17.       "high": "2387.20",
18.       "low": "2385.80",
19.       "close": "2386.50",
20.       "open": "2386.80",
21.       "timestamp": 1723217460.0
22.     }
23.   ]
24. }

复制代码

数据说明

交易时间

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

价格单位

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

合约规格

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

示例代码

Python示例

1. import requests
3. def get_commodity_futures(symbol):
4.     """获取大宗商品期货数据"""
5.     url = "https://api.stocktv.top/futures/querySymbol"
6.     params = {
7.         "symbol": symbol,
8.         "key": "您的API密钥"
9.     }
10.    
11.     response = requests.get(url, params=params)
12.     return response.json()
14. # 获取黄金期货数据
15. gold_data = get_commodity_futures("XAU")
16. print("黄金价格:", gold_data["data"][0]["last_price"])
18. # 获取白银期货数据  
19. silver_data = get_commodity_futures("XAG")
20. print("白银价格:", silver_data["data"][0]["last_price"])
22. # 获取原油期货数据
23. oil_data = get_commodity_futures("CL")
24. print("WTI原油价格:", oil_data["data"][0]["last_price"])

复制代码

JavaScript示例

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

复制代码

实时数据监控示例

1. import time
2. import requests
4. def monitor_gold_price(interval=60):
5.     """监控黄金价格变化"""
6.     previous_price = None
7.    
8.     while True:
9.         try:
10.             data = get_commodity_futures("XAU")
11.             current_price = data["data"][0]["last_price"]
12.             
13.             if previous_price is not None:
14.                 change = current_price - previous_price
15.                 change_pct = (change / previous_price) * 100
16.                 print(f"黄金价格: {current_price} | 变化: {change:+.2f} ({change_pct:+.2f}%)")
17.             
18.             previous_price = current_price
19.             time.sleep(interval)
20.             
21.         except Exception as e:
22.             print(f"获取数据失败: {e}")
23.             time.sleep(30)
25. # 开始监控黄金价格（每分钟更新）
26. monitor_gold_price(60)

复制代码

错误处理

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

• 期货价格具有高波动性，实时数据更新频率较高
  
• 不同期货品种的交易时间可能有所不同
  
• 注意合约到期日和换月移仓问题
  
• 大宗商品价格受全球经济、地缘政治等因素影响较大
  
• API返回的价格为期货合约价格，非现货价格
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！