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: 替换为您的 Keyconst 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) {// 第一步：查找 Symbolconst 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, 1dconst 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>