期货数据对接指南，用于获取黄金、白银、原油等大宗商品的数据。

1. 基础配置

接口域名: https://api.stocktv.top
期货基础路径: /futures
认证方式: URL 参数 key=您的API密钥

2. 核心对接流程

第一步：获取期货品种列表 (查找 Symbol)

由于期货合约代码（Symbol）可能因交易所不同而有所差异（例如黄金可能是 XAU、GC 或 Gold），第一步必须先拉取列表，找到对应的 symbol。

接口: /futures/list
方法: GET
参数: key

请求示例:

GET https://api.stocktv.top/futures/list?key=YOUR_KEY

如何查找:
- 黄金: 搜索关键词 "Gold" 或 "XAU"
- 白银: 搜索关键词 "Silver" 或 "XAG"
- 原油: 搜索关键词 "Oil", "WTI", "Brent" 或 "CL"

第二步：获取实时行情 (Real-time Quote)

获取特定品种的最新买卖价、涨跌幅。

接口: /futures/querySymbol
方法: GET
参数:
- symbol: 品种代码 (第一步获取的)

请求示例 (假设黄金代码为 XAU):

GET https://api.stocktv.top/futures/querySymbol?symbol=XAU&key=YOUR_KEY

响应示例:

{
  "code": 200,
  "data": [
    {
      "symbol": "XAU",
      "name": "Gold Spot",
      "buy": "2350.50",    // 买价
      "sell": "2350.80",   // 卖价
      "last_price": "2350.60", // 最新价
      "chg_pct": "0.45",   // 涨跌幅
      "time": "2024-05-20"
    }
  ]
}

第三步：获取 K 线数据 (Chart Data)

获取用于绘制图表的历史数据。

接口: /futures/kline
方法: GET
参数:
- symbol: 品种代码
- interval: 周期 (注意期货接口的周期定义与股票略有不同)
  - 1, 5, 15, 30, 60 (分钟)
  - 1d (日线)

请求示例:

GET https://api.stocktv.top/futures/kline?symbol=XAU&interval=1d&key=YOUR_KEY

3. 完整代码示例 (HTML + JavaScript)

这是一个完整的演示页面。它包含两个功能：

自动搜索品种：点击按钮自动在列表中查找黄金、白银、原油的 Symbol。
渲染图表：使用找到的 Symbol 绘制 K 线图。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>StockTV 期货行情 (黄金/原油)</title>
    <script src="https://cdn.jsdelivr.net/npm/klinecharts/dist/klinecharts.min.js"></script>
    <style>
        body { font-family: sans-serif; padding: 20px; background-color: #f0f2f5; }
        .container { max-width: 1000px; margin: 0 auto; background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
        .btn-group { margin-bottom: 20px; display: flex; gap: 10px; }
        button { padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer; background-color: #007bff; color: white; font-size: 14px; }
        button:hover { background-color: #0056b3; }
        .status-bar { margin-bottom: 10px; padding: 10px; background: #e6f7ff; border: 1px solid #91d5ff; border-radius: 4px; color: #0050b3; font-size: 14px; }
        #chart { width: 100%; height: 500px; border: 1px solid #eee; }
    </style>
</head>
<body>

<div class="container">
    <h2>StockTV 全球期货数据演示</h2>
    
    <div class="status-bar" id="status">
        请点击下方按钮加载数据...
    </div>

    <div class="btn-group">
        <button onclick="loadCommodity('Gold', '黄金')">加载 黄金 (Gold)</button>
        <button onclick="loadCommodity('Silver', '白银')">加载 白银 (Silver)</button>
        <button onclick="loadCommodity('Oil', '原油')">加载 原油 (Oil)</button>
        <button onclick="loadCommodity('Gas', '天然气')">加载 天然气 (Gas)</button>
    </div>

    <div id="chart"></div>
</div>

<script>
    // === 配置您的 API Key ===
    const API_KEY = 'YOUR_API_KEY'; // TODO: 替换为您的 Key
    const BASE_URL = 'https://api.stocktv.top';

    const chart = klinecharts.init('chart');

    function updateStatus(msg) {
        document.getElementById('status').innerText = msg;
    }

    /**
     * 1. 智能查找品种 Symbol
     * 先获取列表，然后模糊匹配名称
     */
    async function findSymbol(keyword) {
        updateStatus(`正在期货列表中搜索 "${keyword}" ...`);
        const url = `${BASE_URL}/futures/list?key=${API_KEY}`;
        
        try {
            const res = await fetch(url);
            const json = await res.json();
            
            if (json.code === 200 && json.data) {
                // 在列表中查找名称包含 keyword 的项 (不区分大小写)
                const target = json.data.find(item => 
                    item.name.toLowerCase().includes(keyword.toLowerCase()) || 
                    item.symbol.toLowerCase().includes(keyword.toLowerCase())
                );
                return target;
            }
        } catch (e) {
            console.error(e);
            updateStatus("网络请求失败，请检查控制台");
        }
        return null;
    }

    /**
     * 2. 加载数据主流程
     */
    async function loadCommodity(keyword, displayName) {
        // 第一步：查找 Symbol
        const commodity = await findSymbol(keyword);
        
        if (!commodity) {
            updateStatus(`未找到 "${displayName}" 相关的期货合约，请尝试其他关键词。`);
            return;
        }

        const symbol = commodity.symbol;
        updateStatus(`找到合约: ${commodity.name} (${symbol})。正在加载 K 线...`);

        // 第二步：获取 K 线数据 (日线 1d)
        // 注意：期货接口 interval 定义: 1, 5, 15, 30, 60, 1d
        const klineUrl = `${BASE_URL}/futures/kline?symbol=${symbol}&interval=1d&key=${API_KEY}`;
        
        try {
            const res = await fetch(klineUrl);
            const json = await res.json();

            if (json.code === 200 && json.data) {
                // 转换数据格式
                // 期货接口返回: date (字符串时间), open, close, high, low, volume, timestamp (秒级)
                const dataList = json.data.map(item => ({
                    timestamp: item.timestamp * 1000, // 转换为毫秒
                    open: parseFloat(item.open),
                    high: parseFloat(item.high),
                    low: parseFloat(item.low),
                    close: parseFloat(item.close),
                    volume: parseFloat(item.volume)
                }));

                // 排序
                dataList.sort((a, b) => a.timestamp - b.timestamp);

                chart.applyNewData(dataList);
                updateStatus(`成功加载 ${displayName} (${symbol}) 的日线数据，共 ${dataList.length} 条。最新价: ${dataList[dataList.length-1].close}`);
            } else {
                updateStatus(`获取 K 线数据失败: ${json.message}`);
            }
        } catch (e) {
            console.error(e);
            updateStatus("K线请求发生错误");
        }
    }
</script>

</body>
</html>

posted @ 2025-12-11 15:07 CryptoRzz 阅读(6) 评论(0) 收藏举报

刷新页面返回顶部

CryptoRzz