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

概述

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

认证方式

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

key=您的API密钥

基础信息

主要期货品种标识符

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

API端点

1. 期货市场列表

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

请求示例:

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

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "date": "17:57:41",
      "symbol": "XAU",
      "buy": "2385.10",
      "sell": "2385.30",
      "high_price": "2392.60",
      "prev_price": "2378.40",
      "volume": "152306.000",
      "name": "COMEX黄金",
      "time": "2024-08-09",
      "low_price": "2375.20",
      "open_price": "2380.50",
      "last_price": "2385.20",
      "chg": "6.80",
      "chg_pct": "0.29"
    },
    {
      "date": "17:57:56",
      "symbol": "XAG",
      "buy": "28.350",
      "sell": "28.370",
      "high_price": "28.450",
      "prev_price": "28.120",
      "volume": "45218.000",
      "name": "COMEX白银",
      "time": "2024-08-09",
      "low_price": "28.050",
      "open_price": "28.150",
      "last_price": "28.360",
      "chg": "0.240",
      "chg_pct": "0.85"
    },
    {
      "date": "17:58:12",
      "symbol": "CL",
      "buy": "82.45",
      "sell": "82.47",
      "high_price": "83.20",
      "prev_price": "81.80",
      "volume": "285416.000",
      "name": "WTI原油",
      "time": "2024-08-09",
      "low_price": "81.60",
      "open_price": "82.10",
      "last_price": "82.46",
      "chg": "0.66",
      "chg_pct": "0.81"
    },
    {
      "date": "17:58:28",
      "symbol": "BZ",
      "buy": "85.70",
      "sell": "85.72",
      "high_price": "86.40",
      "prev_price": "84.90",
      "volume": "187652.000",
      "name": "布伦特原油",
      "time": "2024-08-09",
      "low_price": "84.70",
      "open_price": "85.20",
      "last_price": "85.71",
      "chg": "0.81",
      "chg_pct": "0.95"
    }
  ]
}

2. 查询特定期货品种

获取黄金、白银或石油的实时行情数据。

请求示例(黄金):

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

请求示例(白银):

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

请求示例(WTI原油):

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

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

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

3. 期货K线数据

获取黄金、白银或石油的历史K线数据。

请求示例(黄金1小时K线):

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

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

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天

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "date": "2024-08-09 17:30:00",
      "volume": "1425",
      "high": "2388.40",
      "low": "2385.20",
      "close": "2386.80",
      "open": "2387.50",
      "timestamp": 1723217400.0
    },
    {
      "date": "2024-08-09 17:31:00",
      "volume": "1286",
      "high": "2387.20",
      "low": "2385.80",
      "close": "2386.50",
      "open": "2386.80",
      "timestamp": 1723217460.0
    }
  ]
}

数据说明

交易时间

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

价格单位

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

合约规格

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

示例代码

Python示例

import requests

def get_commodity_futures(symbol):
    """获取大宗商品期货数据"""
    url = "https://api.stocktv.top/futures/querySymbol"
    params = {
        "symbol": symbol,
        "key": "您的API密钥"
    }
    
    response = requests.get(url, params=params)
    return response.json()

# 获取黄金期货数据
gold_data = get_commodity_futures("XAU")
print("黄金价格:", gold_data["data"][0]["last_price"])

# 获取白银期货数据  
silver_data = get_commodity_futures("XAG")
print("白银价格:", silver_data["data"][0]["last_price"])

# 获取原油期货数据
oil_data = get_commodity_futures("CL")
print("WTI原油价格:", oil_data["data"][0]["last_price"])

JavaScript示例

async function fetchCommodityFutures(symbol) {
  const response = await fetch(
    `https://api.stocktv.top/futures/querySymbol?symbol=${symbol}&key=您的API密钥`
  );
  const data = await response.json();
  return data;
}

// 获取黄金期货数据
fetchCommodityFutures('XAU').then(data => {
  console.log('黄金价格:', data.data[0].last_price);
});

// 获取原油期货数据
fetchCommodityFutures('CL').then(data => {
  console.log('WTI原油价格:', data.data[0].last_price);
});

实时数据监控示例

import time
import requests

def monitor_gold_price(interval=60):
    """监控黄金价格变化"""
    previous_price = None
    
    while True:
        try:
            data = get_commodity_futures("XAU")
            current_price = data["data"][0]["last_price"]
            
            if previous_price is not None:
                change = current_price - previous_price
                change_pct = (change / previous_price) * 100
                print(f"黄金价格: {current_price} | 变化: {change:+.2f} ({change_pct:+.2f}%)")
            
            previous_price = current_price
            time.sleep(interval)
            
        except Exception as e:
            print(f"获取数据失败: {e}")
            time.sleep(30)

# 开始监控黄金价格（每分钟更新）
monitor_gold_price(60)

错误处理

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

注意事项

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

posted @ 2025-09-29 17:19 CryptoRzz 阅读(12) 评论(0) 收藏举报

刷新页面返回顶部

CryptoRzz