博客 / 詳情

返回

期貨數據對接指南，用於獲取黃金、白銀、原油等大宗商品的數據。

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)

這是一個完整的演示頁面。它包含兩個功能：

  1. 自動搜索品種：點擊按鈕自動在列表中查找黃金、白銀、原油的 Symbol。
  2. 渲染圖表：使用找到的 Symbol 繪製 K 線圖。

<!-- end list -->

<!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>
mongodb , mariadb , yaml , 知識 , postgresql
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.