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

金融数据出海
302 阅读5分钟

期货数据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

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

2.2 测试环境

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

2.3 请求头设置

所有HTTP请求需包含：

Content-Type: application/json
key: YOUR_API_KEY

三、核心API接口

3.1 获取期货市场列表

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

请求示例：

GET /futures/list?category=energy

参数说明：

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

响应示例：

{
  "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 查询指定期货行情

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

请求示例：

GET /futures/querySymbol?symbol=CL

参数说明：

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

3.3 获取期货K线数据

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

请求示例：

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

响应示例：

{
  "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请求示例

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集成

@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 错误响应格式

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

七、高级功能

7.1 批量查询接口

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

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

7.2 期权数据查询

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

7.3 跨期价差

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

八、最佳实践

8.1 缓存策略

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 数据归一化处理

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

8.3 限流机制

// 使用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原油CL1,000桶
布伦特原油CO1,000桶
天然气NG10,000 MMBtu
黄金GC100金衡盎司
白银SI5,000金衡盎司
铜HG25,000磅
大豆ZS5,000蒲式耳
玉米ZC5,000蒲式耳

十、技术支持

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

avatar
文章
阅读
粉丝