黄金、原油期货数据API对接文档

本文档提供StockTV期货市场数据API的完整对接指南，包含全球主要期货交易所的实时行情、历史数据、合约信息等核心功能

一、接口概览

1.1 支持期货交易所

交易所代码交易所名称主要期货品种CME芝加哥商品交易所股指、利率、农产品NYMEX纽约商品交易所能源、金属COMEX纽约金属交易所贵金属ICE洲际交易所能源、农产品LME伦敦金属交易所工业金属TOCOM东京商品交易所能源、贵金属SGX新加坡交易所铁矿石、外汇SHFE上海期货交易所金属、能源、化工DCE大连商品交易所农产品、化工CZCE郑州商品交易所农产品1.2 数据特性

• 实时行情：毫秒级延迟
  
• 历史数据：支持最长10年历史K线
  
• 合约信息：完整合约规格、到期日等
  
• 多维度数据：主力合约、连续合约、跨期价差
  
• 数据格式：统一JSON格式
  
• 货币单位：多种货币支持（USD、CNY等）
  

二、接入准备

2.1 获取API Key

联系官方获取密钥：https://t.me/CryptoRzz
2.2 请求基础URL

1. https://api.stocktv.top

复制代码

2.3 请求头设置

1. X-Api-Key: YOUR_API_KEY
2. Content-Type: application/json

复制代码

三、核心接口说明

3.1 期货市场列表

获取所有可用期货品种的概要信息
接口地址：

1. GET /futures/list

复制代码

请求参数：
参数必选说明示例值category否品种类别energy, metal, agricultureexchange否交易所代码CME, NYMEX, SHFE响应示例：

1. {
2.   "code": 200,
3.   "data": [
4.     {
5.       "symbol": "CL",          // 交易代码
6.       "name": "WTI原油",        // 品种名称
7.       "exchange": "NYMEX",      // 交易所
8.       "lastPrice": 82.45,      // 最新价
9.       "change": 0.87,          // 涨跌额
10.       "changePercent": 1.07,   // 涨跌幅%
11.       "openInterest": 185432,  // 持仓量
12.       "volume": 245832,        // 成交量
13.       "updateTime": "2024-09-02T10:15:30Z" // 更新时间
14.     },
15.     {
16.       "symbol": "GC",
17.       "name": "黄金",
18.       "exchange": "COMEX",
19.       "lastPrice": 1956.80,
20.       "change": -5.20,
21.       "changePercent": -0.27,
22.       "openInterest": 452189,
23.       "volume": 124170,
24.       "updateTime": "2024-09-02T10:15:32Z"
25.     }
26.   ]
27. }

复制代码

3.2 查询指定期货行情

获取单个期货品种的详细行情
接口地址：

1. GET /futures/querySymbol

复制代码

请求参数：
参数必选说明示例值symbol是期货代码CL, GC, SI响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "CL",
5.     "name": "WTI原油",
6.     "exchange": "NYMEX",
7.     "lastPrice": 82.45,
8.     "open": 81.80,           // 开盘价
9.     "high": 82.60,           // 最高价
10.     "low": 81.25,            // 最低价
11.     "prevClose": 81.58,      // 前收盘
12.     "volume": 245832,        // 成交量
13.     "openInterest": 185432,  // 持仓量
14.     "settlement": 81.55,     // 结算价
15.     "bid": 82.44,            // 买一价
16.     "ask": 82.46,            // 卖一价
17.     "bidSize": 85,           // 买一量
18.     "askSize": 120,          // 卖一量
19.     "tradingHours": "00:00-24:00", // 交易时段
20.     "expiryDate": "2024-10-20", // 到期日
21.     "contractSize": "1000 barrels", // 合约规模
22.     "tickSize": 0.01,        // 最小变动价位
23.     "tickValue": 10.00       // 最小变动价值
24.   }
25. }

复制代码

3.3 获取期货K线数据

获取历史K线数据
接口地址：

1. GET /futures/kline

复制代码

请求参数：
参数必选说明示例值symbol是期货代码CLinterval是时间粒度1m, 5m, 15m, 1h, 4h, 1dfrom否开始时间(YYYYMMDDHHmm)202409010000to否结束时间(YYYYMMDDHHmm)202409022359响应示例：

1. {
2.   "code": 200,
3.   "data": [
4.     {
5.       "timestamp": 1725004800000, // 时间戳(ms)
6.       "open": 82.12,             // 开盘价
7.       "high": 82.48,             // 最高价
8.       "low": 82.05,              // 最低价
9.       "close": 82.32,            // 收盘价
10.       "volume": 12452,           // 成交量
11.       "openInterest": 185120     // 持仓量
12.     },
13.     {
14.       "timestamp": 1725004860000,
15.       "open": 82.33,
16.       "high": 82.40,
17.       "low": 82.28,
18.       "close": 82.35,
19.       "volume": 8560,
20.       "openInterest": 185150
21.     }
22.   ]
23. }

复制代码

3.4 获取合约信息

获取期货合约详细信息
接口地址：

1. GET /futures/contract

复制代码

请求参数：
参数必选说明示例值symbol是期货代码CLmonth否合约月份202410响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "CL",
5.     "contractMonth": "2024-10",
6.     "firstTradingDate": "2024-09-10",
7.     "lastTradingDate": "2024-10-20",
8.     "firstNoticeDate": "2024-10-05",
9.     "lastNoticeDate": "2024-10-15",
10.     "firstDeliveryDate": "2024-10-21",
11.     "lastDeliveryDate": "2024-10-25",
12.     "contractSize": "1000 barrels",
13.     "priceQuotation": "USD per barrel",
14.     "tickSize": 0.01,
15.     "tickValue": 10.00,
16.     "tradingHours": "00:00-24:00",
17.     "productCode": "CL",
18.     "exchange": "NYMEX"
19.   }
20. }

复制代码

四、高级数据接口

4.1 主力合约与连续合约

获取主力合约和连续合约数据
接口地址：

1. GET /futures/continuous

复制代码

请求参数：
参数必选说明示例值symbol是期货代码CLtype是合约类型main(主力), continuous(连续)响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "CL",
5.     "type": "main",
6.     "currentContract": "CL2024V4", // 当前主力合约
7.     "nextContract": "CL2024X4",   // 下一个主力合约
8.     "rolloverDate": "2024-09-15",  // 换月日期
9.     "historicalContracts": [       // 历史主力合约
10.       "CL2024U4",
11.       "CL2024Q4",
12.       "CL2024N4"
13.     ]
14.   }
15. }

复制代码

4.2 价差交易数据

获取跨期价差数据
接口地址：

1. GET /futures/spread

复制代码

请求参数：
参数必选说明示例值symbol1是第一个合约CL2024V4symbol2是第二个合约CL2024X4响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol1": "CL2024V4",
5.     "symbol2": "CL2024X4",
6.     "price1": 82.45,
7.     "price2": 82.20,
8.     "spread": 0.25,               // 价差
9.     "spreadPercent": 0.30,        // 价差百分比
10.     "volume": 1245,               // 价差交易量
11.     "openInterest": 8560,         // 价差持仓量
12.     "historicalSpreads": [        // 历史价差
13.       {
14.         "timestamp": 1725004800000,
15.         "spread": 0.22
16.       },
17.       {
18.         "timestamp": 1725004860000,
19.         "spread": 0.24
20.       }
21.     ]
22.   }
23. }

复制代码

4.3 持仓报告

获取交易所持仓报告数据
接口地址：

1. GET /futures/cot

复制代码

请求参数：
参数必选说明示例值symbol是期货代码CLreportDate否报告日期(YYYYMMDD)20240901响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "CL",
5.     "reportDate": "2024-09-01",
6.     "commercialLong": 452189,     // 商业多头
7.     "commercialShort": 245832,    // 商业空头
8.     "nonCommercialLong": 185432,   // 非商业多头
9.     "nonCommercialShort": 124170,  // 非商业空头
10.     "nonReportableLong": 8560,     // 非报告多头
11.     "nonReportableShort": 12452,  // 非报告空头
12.     "openInterest": 892000,       // 总持仓量
13.     "change": 12450               // 持仓变化
14.   }
15. }

复制代码

五、实时数据推送

5.1 WebSocket连接

1. wss://ws-api.stocktv.top/connect?key=YOUR_API_KEY

复制代码

5.2 订阅消息

1. {
2.   "action": "subscribe",
3.   "channels": ["futures:CL", "futures:GC"]
4. }

复制代码

5.3 实时数据格式

1. {
2.   "channel": "futures:CL",
3.   "data": {
4.     "symbol": "CL",
5.     "last": 82.46,          // 最新价
6.     "change": 0.88,         // 涨跌额
7.     "changePercent": 1.08,  // 涨跌幅
8.     "volume": 245901,       // 成交量
9.     "openInterest": 185450, // 持仓量
10.     "bid": 82.45,           // 买一价
11.     "ask": 82.47,           // 卖一价
12.     "bidSize": 85,          // 买一量
13.     "askSize": 120,         // 卖一量
14.     "high": 82.60,          // 最高价
15.     "low": 81.25,           // 最低价
16.     "open": 81.80,          // 开盘价
17.     "prevClose": 81.58,     // 前收盘
18.     "settlement": 81.55,    // 结算价
19.     "timestamp": 1725008213 // 时间戳
20.   }
21. }

复制代码

5.4 心跳机制

客户端需每30秒发送心跳消息：

1. {"action": "ping"}

复制代码

六、代码示例

6.1 Python获取期货数据

1. import requests
3. def get_futures_list(category=None):
4.     """获取期货市场列表"""
5.     url = "https://api.stocktv.top/futures/list"
6.     params = {"key": "YOUR_API_KEY"}
7.     if category:
8.         params["category"] = category
9.    
10.     try:
11.         response = requests.get(url, params=params)
12.         if response.status_code == 200:
13.             data = response.json()
14.             if data["code"] == 200:
15.                 for futures in data["data"]:
16.                     print(f"{futures['symbol']}: {futures['name']} - {futures['lastPrice']}")
17.             else:
18.                 print(f"API Error: {data['message']}")
19.         else:
20.             print(f"Request failed with status: {response.status_code}")
21.     except Exception as e:
22.         print(f"Error fetching futures list: {str(e)}")
24. # 获取能源类期货
25. get_futures_list(category="energy")

复制代码

6.2 Java获取K线数据

1. import okhttp3.OkHttpClient;
2. import okhttp3.Request;
3. import okhttp3.Response;
4. import org.json.JSONArray;
5. import org.json.JSONObject;
7. public class FuturesKline {
8.     public static void main(String[] args) throws Exception {
9.         OkHttpClient client = new OkHttpClient();
10.         
11.         String symbol = "CL";
12.         String url = "https://api.stocktv.top/futures/kline?symbol=" + symbol + "&interval=1h&key=YOUR_API_KEY";
13.         
14.         Request request = new Request.Builder()
15.                 .url(url)
16.                 .build();
17.         
18.         try (Response response = client.newCall(request).execute()) {
19.             if (response.isSuccessful()) {
20.                 JSONObject json = new JSONObject(response.body().string());
21.                 if (json.getInt("code") == 200) {
22.                     JSONArray data = json.getJSONArray("data");
23.                     for (int i = 0; i < data.length(); i++) {
24.                         JSONObject kline = data.getJSONObject(i);
25.                         System.out.println("Time: " + kline.getLong("timestamp") +
26.                                           " | Close: " + kline.getDouble("close"));
27.                     }
28.                 }
29.             }
30.         }
31.     }
32. }

复制代码

6.3 Node.js实时数据订阅

1. const WebSocket = require('ws');
3. const wsUrl = 'wss://ws-api.stocktv.top/connect?key=YOUR_API_KEY';
4. const ws = new WebSocket(wsUrl);
6. ws.on('open', () => {
7.   console.log('Connected to Futures API');
8.   
9.   // 订阅WTI原油和黄金
10.   ws.send(JSON.stringify({
11.     action: 'subscribe',
12.     channels: ['futures:CL', 'futures:GC']
13.   }));
14.   
15.   // 心跳机制
16.   setInterval(() => {
17.     ws.send(JSON.stringify({action: 'ping'}));
18.   }, 30000);
19. });
21. ws.on('message', (data) => {
22.   const message = JSON.parse(data);
23.   
24.   if (message.channel) {
25.     const symbol = message.channel.split(':')[1];
26.     console.log(`[${symbol}] ${message.data.last} (${message.data.changePercent}%)`);
27.   }
28. });
30. ws.on('close', () => {
31.   console.log('Disconnected from Futures API');
32. });

复制代码

七、最佳实践

7.1 数据缓存策略

1. from cachetools import TTLCache
2. import time
4. # 创建缓存，有效期5秒
5. futures_cache = TTLCache(maxsize=100, ttl=5)
7. def get_futures_quote(symbol):
8.     """获取期货行情（带缓存）"""
9.     # 检查缓存
10.     if symbol in futures_cache:
11.         return futures_cache[symbol]
12.    
13.     # 调用API获取数据
14.     quote = fetch_from_api(symbol)
15.    
16.     # 存入缓存
17.     if quote:
18.         futures_cache[symbol] = quote
19.    
20.     return quote

复制代码

7.2 错误处理与重试

1. import requests
2. import time
4. def fetch_with_retry(url, params, max_retries=3):
5.     """带重试机制的API请求"""
6.     for attempt in range(max_retries):
7.         try:
8.             response = requests.get(url, params=params, timeout=5)
9.             if response.status_code == 200:
10.                 data = response.json()
11.                 if data.get("code") == 200:
12.                     return data
13.                 elif data.get("code") == 429:  # 请求过多
14.                     retry_after = int(data.get("retryAfter", 10))
15.                     print(f"请求过于频繁，等待 {retry_after} 秒后重试...")
16.                     time.sleep(retry_after)
17.                 else:
18.                     print(f"API返回错误: {data.get('message')}")
19.             else:
20.                 print(f"请求失败，状态码: {response.status_code}")
21.         except Exception as e:
22.             print(f"请求异常: {str(e)}")
23.         
24.         if attempt < max_retries - 1:
25.             wait = 2 ** attempt  # 指数退避
26.             print(f"等待 {wait} 秒后重试 (尝试 {attempt+1}/{max_retries})")
27.             time.sleep(wait)
28.    
29.     print(f"请求失败，已达最大重试次数 {max_retries}")
30.     return None

复制代码

7.3 实时数据批处理

1. class FuturesDataProcessor:
2.     def __init__(self, batch_size=10, batch_interval=0.5):
3.         self.batch_size = batch_size
4.         self.batch_interval = batch_interval
5.         self.buffer = {}
6.         self.last_process_time = time.time()
7.    
8.     def add_data(self, symbol, data):
9.         """添加实时数据到缓冲区"""
10.         if symbol not in self.buffer:
11.             self.buffer[symbol] = []
12.         
13.         self.buffer[symbol].append(data)
14.         
15.         # 检查是否达到批处理条件
16.         current_time = time.time()
17.         if (len(self.buffer[symbol]) >= self.batch_size or
18.             current_time - self.last_process_time >= self.batch_interval):
19.             self.process_batch(symbol)
20.             self.last_process_time = current_time
21.    
22.     def process_batch(self, symbol):
23.         """处理缓冲区的数据"""
24.         if symbol not in self.buffer or not self.buffer[symbol]:
25.             return
26.         
27.         data_points = self.buffer[symbol]
28.         
29.         # 计算统计指标
30.         prices = [d["last"] for d in data_points]
31.         volumes = [d["volume"] for d in data_points]
32.         oi_changes = [d.get("openInterestChange", 0) for d in data_points]
33.         
34.         avg_price = sum(prices) / len(prices)
35.         max_price = max(prices)
36.         min_price = min(prices)
37.         total_volume = sum(volumes)
38.         total_oi_change = sum(oi_changes)
39.         
40.         print(f"\n{symbol} 实时数据统计 (最近 {len(data_points)} 个更新):")
41.         print(f"平均价格: {avg_price:.2f}, 最高: {max_price:.2f}, 最低: {min_price:.2f}")
42.         print(f"总成交量: {total_volume}, 总持仓变化: {total_oi_change}")
43.         
44.         # 清空缓冲区
45.         self.buffer[symbol] = []

复制代码

八、数据字典

8.1 主要期货品种

代码品种名称交易所合约规模CLWTI原油NYMEX1000桶GC黄金COMEX100金衡盎司SI白银COMEX5000金衡盎司NG天然气NYMEX10000MMBtuZS大豆CBOT5000蒲式耳ZC玉米CBOT5000蒲式耳ZW小麦CBOT5000蒲式耳6E欧元期货CME125,000欧元ES标普500指数期货CME$50×指数NQ纳斯达克100指数期货CME$20×指数十、附录

10.1 常见问题解答

Q: 如何获取不同到期日的合约数据？
A: 使用完整合约代码，例如CL2024V4表示2024年10月WTI原油合约
Q: 支持哪些历史数据粒度？
A: 支持1分钟、5分钟、15分钟、30分钟、1小时、4小时、日线、周线、月线
10.2 错误代码表

错误码含义解决方案400请求参数错误检查请求参数401未授权检查API Key403禁止访问确认账户权限404资源不存在检查请求路径500服务器错误联系技术支持
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！