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

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

news 2025/9/24 15:56:38

本文档提供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

https://api.stocktv.top

2.3 请求头设置

X-Api-Key: YOUR_API_KEY
Content-Type: application/json

三、核心接口说明

3.1 期货市场列表

获取所有可用期货品种的概要信息

接口地址：

GET /futures/list

请求参数：

参数 必选 说明 示例值
category 否 品种类别 energy, metal, agriculture
exchange 否 交易所代码 CME, NYMEX, SHFE

响应示例：

{"code": 200,"data": [{"symbol": "CL",          // 交易代码"name": "WTI原油",        // 品种名称"exchange": "NYMEX",      // 交易所"lastPrice": 82.45,      // 最新价"change": 0.87,          // 涨跌额"changePercent": 1.07,   // 涨跌幅%"openInterest": 185432,  // 持仓量"volume": 245832,        // 成交量"updateTime": "2024-09-02T10:15:30Z" // 更新时间},{"symbol": "GC","name": "黄金","exchange": "COMEX","lastPrice": 1956.80,"change": -5.20,"changePercent": -0.27,"openInterest": 452189,"volume": 124170,"updateTime": "2024-09-02T10:15:32Z"}]
}

3.2 查询指定期货行情

获取单个期货品种的详细行情

接口地址：

GET /futures/querySymbol

请求参数：

参数 必选 说明 示例值
symbol 是 期货代码 CL, GC, SI

响应示例：

{"code": 200,"data": {"symbol": "CL","name": "WTI原油","exchange": "NYMEX","lastPrice": 82.45,"open": 81.80,           // 开盘价"high": 82.60,           // 最高价"low": 81.25,            // 最低价"prevClose": 81.58,      // 前收盘"volume": 245832,        // 成交量"openInterest": 185432,  // 持仓量"settlement": 81.55,     // 结算价"bid": 82.44,            // 买一价"ask": 82.46,            // 卖一价"bidSize": 85,           // 买一量"askSize": 120,          // 卖一量"tradingHours": "00:00-24:00", // 交易时段"expiryDate": "2024-10-20", // 到期日"contractSize": "1000 barrels", // 合约规模"tickSize": 0.01,        // 最小变动价位"tickValue": 10.00       // 最小变动价值}
}

3.3 获取期货K线数据

获取历史K线数据

接口地址：

GET /futures/kline

请求参数：

参数 必选 说明 示例值
symbol 是 期货代码 CL
interval 是 时间粒度 1m, 5m, 15m, 1h, 4h, 1d
from 否 开始时间(YYYYMMDDHHmm) 202409010000
to 否 结束时间(YYYYMMDDHHmm) 202409022359

响应示例：

{"code": 200,"data": [{"timestamp": 1725004800000, // 时间戳(ms)"open": 82.12,             // 开盘价"high": 82.48,             // 最高价"low": 82.05,              // 最低价"close": 82.32,            // 收盘价"volume": 12452,           // 成交量"openInterest": 185120     // 持仓量},{"timestamp": 1725004860000,"open": 82.33,"high": 82.40,"low": 82.28,"close": 82.35,"volume": 8560,"openInterest": 185150}]
}

3.4 获取合约信息

获取期货合约详细信息

接口地址：

GET /futures/contract

请求参数：

参数 必选 说明 示例值
symbol 是 期货代码 CL
month 否 合约月份 202410

响应示例：

{"code": 200,"data": {"symbol": "CL","contractMonth": "2024-10","firstTradingDate": "2024-09-10","lastTradingDate": "2024-10-20","firstNoticeDate": "2024-10-05","lastNoticeDate": "2024-10-15","firstDeliveryDate": "2024-10-21","lastDeliveryDate": "2024-10-25","contractSize": "1000 barrels","priceQuotation": "USD per barrel","tickSize": 0.01,"tickValue": 10.00,"tradingHours": "00:00-24:00","productCode": "CL","exchange": "NYMEX"}
}

四、高级数据接口

4.1 主力合约与连续合约

获取主力合约和连续合约数据

接口地址：

GET /futures/continuous

请求参数：

参数 必选 说明 示例值
symbol 是 期货代码 CL
type 是 合约类型 main(主力), continuous(连续)

响应示例：

{"code": 200,"data": {"symbol": "CL","type": "main","currentContract": "CL2024V4", // 当前主力合约"nextContract": "CL2024X4",   // 下一个主力合约"rolloverDate": "2024-09-15",  // 换月日期"historicalContracts": [       // 历史主力合约"CL2024U4","CL2024Q4","CL2024N4"]}
}

4.2 价差交易数据

获取跨期价差数据

接口地址：

GET /futures/spread

请求参数：

参数 必选 说明 示例值
symbol1 是 第一个合约 CL2024V4
symbol2 是 第二个合约 CL2024X4

响应示例：

{"code": 200,"data": {"symbol1": "CL2024V4","symbol2": "CL2024X4","price1": 82.45,"price2": 82.20,"spread": 0.25,               // 价差"spreadPercent": 0.30,        // 价差百分比"volume": 1245,               // 价差交易量"openInterest": 8560,         // 价差持仓量"historicalSpreads": [        // 历史价差{"timestamp": 1725004800000,"spread": 0.22},{"timestamp": 1725004860000,"spread": 0.24}]}
}

4.3 持仓报告

获取交易所持仓报告数据

接口地址：

GET /futures/cot

请求参数：

参数 必选 说明 示例值
symbol 是 期货代码 CL
reportDate 否 报告日期(YYYYMMDD) 20240901

响应示例：

{"code": 200,"data": {"symbol": "CL","reportDate": "2024-09-01","commercialLong": 452189,     // 商业多头"commercialShort": 245832,    // 商业空头"nonCommercialLong": 185432,   // 非商业多头"nonCommercialShort": 124170,  // 非商业空头"nonReportableLong": 8560,     // 非报告多头"nonReportableShort": 12452,  // 非报告空头"openInterest": 892000,       // 总持仓量"change": 12450               // 持仓变化}
}

五、实时数据推送

5.1 WebSocket连接

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

5.2 订阅消息

{"action": "subscribe","channels": ["futures:CL", "futures:GC"]
}

5.3 实时数据格式

{"channel": "futures:CL","data": {"symbol": "CL","last": 82.46,          // 最新价"change": 0.88,         // 涨跌额"changePercent": 1.08,  // 涨跌幅"volume": 245901,       // 成交量"openInterest": 185450, // 持仓量"bid": 82.45,           // 买一价"ask": 82.47,           // 卖一价"bidSize": 85,          // 买一量"askSize": 120,         // 卖一量"high": 82.60,          // 最高价"low": 81.25,           // 最低价"open": 81.80,          // 开盘价"prevClose": 81.58,     // 前收盘"settlement": 81.55,    // 结算价"timestamp": 1725008213 // 时间戳}
}

5.4 心跳机制

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

{"action": "ping"}

六、代码示例

6.1 Python获取期货数据

import requestsdef get_futures_list(category=None):"""获取期货市场列表"""url = "https://api.stocktv.top/futures/list"params = {"key": "YOUR_API_KEY"}if category:params["category"] = categorytry:response = requests.get(url, params=params)if response.status_code == 200:data = response.json()if data["code"] == 200:for futures in data["data"]:print(f"{futures['symbol']}: {futures['name']} - {futures['lastPrice']}")else:print(f"API Error: {data['message']}")else:print(f"Request failed with status: {response.status_code}")except Exception as e:print(f"Error fetching futures list: {str(e)}")# 获取能源类期货
get_futures_list(category="energy")

6.2 Java获取K线数据

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import org.json.JSONArray;
import org.json.JSONObject;public class FuturesKline {public static void main(String[] args) throws Exception {OkHttpClient client = new OkHttpClient();String symbol = "CL";String url = "https://api.stocktv.top/futures/kline?symbol=" + symbol + "&interval=1h&key=YOUR_API_KEY";Request request = new Request.Builder().url(url).build();try (Response response = client.newCall(request).execute()) {if (response.isSuccessful()) {JSONObject json = new JSONObject(response.body().string());if (json.getInt("code") == 200) {JSONArray data = json.getJSONArray("data");for (int i = 0; i < data.length(); i++) {JSONObject kline = data.getJSONObject(i);System.out.println("Time: " + kline.getLong("timestamp") + " | Close: " + kline.getDouble("close"));}}}}}
}

6.3 Node.js实时数据订阅

const WebSocket = require('ws');const wsUrl = 'wss://ws-api.stocktv.top/connect?key=YOUR_API_KEY';
const ws = new WebSocket(wsUrl);ws.on('open', () => {console.log('Connected to Futures API');// 订阅WTI原油和黄金ws.send(JSON.stringify({action: 'subscribe',channels: ['futures:CL', 'futures:GC']}));// 心跳机制setInterval(() => {ws.send(JSON.stringify({action: 'ping'}));}, 30000);
});ws.on('message', (data) => {const message = JSON.parse(data);if (message.channel) {const symbol = message.channel.split(':')[1];console.log(`[${symbol}] ${message.data.last} (${message.data.changePercent}%)`);}
});ws.on('close', () => {console.log('Disconnected from Futures API');
});

七、最佳实践

7.1 数据缓存策略

from cachetools import TTLCache
import time# 创建缓存，有效期5秒
futures_cache = TTLCache(maxsize=100, ttl=5)def get_futures_quote(symbol):"""获取期货行情（带缓存）"""# 检查缓存if symbol in futures_cache:return futures_cache[symbol]# 调用API获取数据quote = fetch_from_api(symbol)# 存入缓存if quote:futures_cache[symbol] = quotereturn quote

7.2 错误处理与重试

import requests
import timedef fetch_with_retry(url, params, max_retries=3):"""带重试机制的API请求"""for attempt in range(max_retries):try:response = requests.get(url, params=params, timeout=5)if response.status_code == 200:data = response.json()if data.get("code") == 200:return dataelif data.get("code") == 429:  # 请求过多retry_after = int(data.get("retryAfter", 10))print(f"请求过于频繁，等待 {retry_after} 秒后重试...")time.sleep(retry_after)else:print(f"API返回错误: {data.get('message')}")else:print(f"请求失败，状态码: {response.status_code}")except Exception as e:print(f"请求异常: {str(e)}")if attempt < max_retries - 1:wait = 2 ** attempt  # 指数退避print(f"等待 {wait} 秒后重试 (尝试 {attempt+1}/{max_retries})")time.sleep(wait)print(f"请求失败，已达最大重试次数 {max_retries}")return None

7.3 实时数据批处理

class FuturesDataProcessor:def __init__(self, batch_size=10, batch_interval=0.5):self.batch_size = batch_sizeself.batch_interval = batch_intervalself.buffer = {}self.last_process_time = time.time()def add_data(self, symbol, data):"""添加实时数据到缓冲区"""if symbol not in self.buffer:self.buffer[symbol] = []self.buffer[symbol].append(data)# 检查是否达到批处理条件current_time = time.time()if (len(self.buffer[symbol]) >= self.batch_size or current_time - self.last_process_time >= self.batch_interval):self.process_batch(symbol)self.last_process_time = current_timedef process_batch(self, symbol):"""处理缓冲区的数据"""if symbol not in self.buffer or not self.buffer[symbol]:returndata_points = self.buffer[symbol]# 计算统计指标prices = [d["last"] for d in data_points]volumes = [d["volume"] for d in data_points]oi_changes = [d.get("openInterestChange", 0) for d in data_points]avg_price = sum(prices) / len(prices)max_price = max(prices)min_price = min(prices)total_volume = sum(volumes)total_oi_change = sum(oi_changes)print(f"\n{symbol} 实时数据统计 (最近 {len(data_points)} 个更新):")print(f"平均价格: {avg_price:.2f}, 最高: {max_price:.2f}, 最低: {min_price:.2f}")print(f"总成交量: {total_volume}, 总持仓变化: {total_oi_change}")# 清空缓冲区self.buffer[symbol] = []

八、数据字典

8.1 主要期货品种

代码 品种名称 交易所 合约规模
CL WTI原油 NYMEX 1000桶
GC 黄金 COMEX 100金衡盎司
SI 白银 COMEX 5000金衡盎司
NG 天然气 NYMEX 10000MMBtu
ZS 大豆 CBOT 5000蒲式耳
ZC 玉米 CBOT 5000蒲式耳
ZW 小麦 CBOT 5000蒲式耳
6E 欧元期货 CME 125,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 Key
403 禁止访问 确认账户权限
404 资源不存在 检查请求路径
500 服务器错误 联系技术支持
http://www.hskmm.com/?act=detail&tid=15871

相关文章：

  • 我的笔记方案
  • 聊聊前序、中序、后序表达式
  • flink书籍 - --
  • 详述大模型备案
  • Asp.Net Core 鉴权授权
  • 124
  • 我的笔记记录方案
  • AT_arc156_d [ARC156D] Xor Sum 5
  • iOS Provisioning Profile 证书 描述文件
  • 计算快速付氏变换FFT前需要加窗函数
  • 直播预告｜ PostgreSQL 与 IvorySQL 在云原生时代的演进与实践
  • KGDB（Kernel GNU Debugger）工具使用方法详解 - 详解
  • Wallpaper Engine v2.7.3 动态壁纸软件-内含数百款动态皮肤 - 实践
  • 力扣155题 最小栈
  • Markdown语法
  • 压垮项目经理的“三座大山”：时间、成本、质量的生存法则与破局工具
  • 最新微信机器人开发教程
  • 金蝶AAS (Apusic Application Server) v10 部署SuperMap iServer 2025 详细教程
  • AI智能会话原型解析：知识问答与知识库管理的设计思路（附模版）
  • Linux - Nginx 文件访问403 forbidden = 授权 chmod -R 777 文件名称
  • 爬虫逆向--Day25Day26--原型链补环境
  • 阻抗匹配技术：信号完整性与功率传输的基石​​
  • 萝卜视频小程序管理系统：多场景适配的短视频商业解决方案
  • 栈与队列专题
  • 读书笔记：为什么你的索引“罢工”了？六种常见原因解析
  • 平面网格材质
  • OSCP备考成功指南：9大实用学习技巧
  • 设备租赁系统：建材租赁行业的高效管理解决方案
  • NOI 2025 题解
  • 迈特海外短剧多语言版 SAAS 开源系统：助力短剧出海，开启全球盈利新赛道