黄金金融期货数据API对接技术文档

期货数据API对接技术文档

本文档提供StockTV期货数据API的完整对接指南，帮助开发者快速集成全球期货市场实时行情数据

一、接口概览

1.1 支持期货品种

类别	代表品种	交易所
金属	黄金、白银、铜、铝	COMEX, LME, SHFE
能源	原油、天然气、燃料油	NYMEX, ICE, INE
农产品	大豆、玉米、小麦、棉花	CBOT, CME, ZCE
金融期货	股指期货、国债期货	CME, EUREX, CFFEX
软商品	咖啡、糖、可可	ICE, NYBOT

1.2 接口特性

数据时效性：交易所直连，延迟<500ms
历史数据：支持最长5年历史K线
数据格式：统一JSON格式
接入方式：HTTP REST + WebSocket

二、快速开始

2.1 获取API Key

联系官方获取密钥：https://t.me/CryptoRzz

2.2 测试环境

复制代码

API地址：https://api.stocktv.top
WebSocket：wss://ws-api.stocktv.top

2.3 请求头设置

所有HTTP请求需包含：

http 复制代码

Content-Type: application/json
key: YOUR_API_KEY

三、核心API接口

3.1 获取期货市场列表

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

请求示例：

http 复制代码

GET /futures/list?category=energy

参数说明：

参数	必选	说明	示例值
`category`	否	品种类别	energy, metal, agriculture

响应示例：

json 复制代码

{
  "code": 200,
  "data": [
    {
      "symbol": "CL",          // 交易代码
      "name": "WTI原油",        // 品种名称
      "exchange": "NYMEX",      // 交易所
      "lastPrice": 82.45,      // 最新价
      "change": 0.87,          // 涨跌额
      "changePercent": 1.07,   // 涨跌幅(%)
      "openInterest": 185432,  // 持仓量
      "updateTime": "2025-09-02T10:15:30Z" // 更新时间
    }
  ]
}

3.2 查询指定期货行情

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

请求示例：

http 复制代码

GET /futures/querySymbol?symbol=CL

参数说明：

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

响应示例：

json 复制代码

{
  "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,        // 成交量
    "bid": 82.44,            // 买一价
    "ask": 82.46,            // 卖一价
    "settlement": 81.55,     // 结算价
    "tradingHours": "00:00-24:00", // 交易时段
    "expiryDate": "2025-10-20" // 到期日
  }
}

3.3 获取期货K线数据

接口功能：获取历史K线数据

请求示例：

http 复制代码

GET /futures/kline?symbol=CL&interval=15m&from=202509010000&to=202509022359

参数说明：

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

响应示例：

json 复制代码

{
  "code": 200,
  "data": [
    {
      "timestamp": 1755008100000, // K线起始时间(毫秒)
      "open": 82.12,             // 开盘价
      "high": 82.48,             // 最高价
      "low": 82.05,              // 最低价
      "close": 82.32,            // 收盘价
      "volume": 12452,           // 成交量
      "openInterest": 185120     // 持仓量
    },
    // 更多K线数据...
  ]
}

四、代码示例

5.1 Python请求示例

python 复制代码

import requests

url = "https://api.stocktv.top/futures/querySymbol"
params = {"symbol": "CL"}
headers = {
    "key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
if response.status_code == 200:
    data = response.json()
    print(f"WTI原油最新价: {data['data']['lastPrice']}")

5.2 Java/Spring Boot集成

java 复制代码

@Service
public class FuturesService {
    
    @Value("${futures.api.url}")
    private String apiUrl;
    
    @Value("${futures.api.key}")
    private String apiKey;
    
    public FuturesData getFuturesData(String symbol) {
        WebClient client = WebClient.create(apiUrl);
        
        return client.get()
            .uri("/futures/querySymbol?symbol={symbol}", symbol)
            .header("key", apiKey)
            .retrieve()
            .bodyToMono(FuturesData.class)
            .block();
    }
    
    @Data
    public static class FuturesData {
        private String symbol;
        private String name;
        private double lastPrice;
        private double change;
        private double changePercent;
        // 其他字段...
    }
}

6.1 常见错误码

状态码	含义	解决方案
401	未授权	检查API Key是否正确
403	禁止访问	确认账户权限是否有效
404	资源不存在	检查请求路径是否正确
500	服务器错误	联系技术支持

6.2 错误响应格式

json 复制代码

{
  "code": 429,
  "message": "请求过于频繁，请稍后再试",
  "retryAfter": 30 // 重试等待时间(秒)
}

七、高级功能

7.1 批量查询接口

http 复制代码

POST /futures/batch
Content-Type: application/json

{
  "symbols": ["CL", "GC", "SI"]
}

7.2 期权数据查询

http 复制代码

GET /futures/options?underlying=CL&expiry=202510

7.3 跨期价差

http 复制代码

GET /futures/spread?symbol1=CL202510&symbol2=CL202512

八、最佳实践

8.1 缓存策略

python 复制代码

from cachetools import TTLCache

# 创建缓存(5秒过期)
cache = TTLCache(maxsize=100, ttl=5)

def get_futures_data(symbol):
    if symbol in cache:
        return cache[symbol]
    
    # API请求
    data = api_request(symbol)
    cache[symbol] = data
    return data

8.2 数据归一化处理

javascript 复制代码

// 统一处理价格精度
function normalizePrice(price, symbol) {
  const precisionMap = {
    'CL': 2,   // 原油保留2位小数
    'GC': 2,   // 黄金保留2位小数
    'SI': 3    // 白银保留3位小数
  };
  
  return price.toFixed(precisionMap[symbol] || 2);
}

8.3 限流机制

java 复制代码

// 使用Guava RateLimiter
private final RateLimiter rateLimiter = RateLimiter.create(10); // 10请求/秒

public FuturesData getDataWithRateLimit(String symbol) {
    if (rateLimiter.tryAcquire()) {
        return getFuturesData(symbol);
    }
    throw new RateLimitExceededException();
}

九、数据字典

9.1 交易所代码

代码	交易所名称	所在地
CME	芝加哥商品交易所	美国
NYMEX	纽约商品交易所	美国
COMEX	纽约金属交易所	美国
ICE	洲际交易所	美国
LME	伦敦金属交易所	英国
EUREX	欧洲期货交易所	德国
TOCOM	东京商品交易所	日本
SGX	新加坡交易所	新加坡
SHFE	上海期货交易所	中国
CFFEX	中国金融期货交易所	中国

9.2 期货品种代码

品种	代码	合约大小
WTI原油	CL	1,000桶
布伦特原油	CO	1,000桶
天然气	NG	10,000 MMBtu
黄金	GC	100金衡盎司
白银	SI	5,000金衡盎司
铜	HG	25,000磅
大豆	ZS	5,000蒲式耳
玉米	ZC	5,000蒲式耳

十、技术支持

官方文档：https://stocktv.top/

开发者可根据实际需求选择合适的接口和接入方式，快速实现期货行情功能。建议生产环境部署前进行充分测试，并设置合适的限流和容错机制。