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 线图。
<!DOCTYPEhtml><htmllang="zh-CN"><head><metacharset="UTF-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><title>StockTV 期货行情 (黄金/原油)</title><scriptsrc="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 8pxrgba(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><divclass="container"><h2>StockTV 全球期货数据演示</h2><divclass="status-bar"id="status">请点击下方按钮加载数据...</div><divclass="btn-group"><buttononclick="loadCommodity('Gold','黄金')">加载 黄金 (Gold)</button><buttononclick="loadCommodity('Silver','白银')">加载 白银 (Silver)</button><buttononclick="loadCommodity('Oil','原油')">加载 原油 (Oil)</button><buttononclick="loadCommodity('Gas','天然气')">加载 天然气 (Gas)</button></div><divid="chart"></div></div><script>// === 配置您的 API Key ===constAPI_KEY='YOUR_API_KEY';// TODO: 替换为您的 KeyconstBASE_URL='https://api.stocktv.top';constchart=klinecharts.init('chart');functionupdateStatus(msg){document.getElementById('status').innerText=msg;}/** * 1. 智能查找品种 Symbol * 先获取列表，然后模糊匹配名称 */asyncfunctionfindSymbol(keyword){updateStatus(`正在期货列表中搜索 "${keyword}" ...`);consturl=`${BASE_URL}/futures/list?key=${API_KEY}`;try{constres=awaitfetch(url);constjson=awaitres.json();if(json.code===200&&json.data){// 在列表中查找名称包含 keyword 的项 (不区分大小写)consttarget=json.data.find(item=>item.name.toLowerCase().includes(keyword.toLowerCase())||item.symbol.toLowerCase().includes(keyword.toLowerCase()));returntarget;}}catch(e){console.error(e);updateStatus("网络请求失败，请检查控制台");}returnnull;}/** * 2. 加载数据主流程 */asyncfunctionloadCommodity(keyword,displayName){// 第一步：查找 Symbolconstcommodity=awaitfindSymbol(keyword);if(!commodity){updateStatus(`未找到 "${displayName}" 相关的期货合约，请尝试其他关键词。`);return;}constsymbol=commodity.symbol;updateStatus(`找到合约:${commodity.name}(${symbol})。正在加载 K 线...`);// 第二步：获取 K 线数据 (日线 1d)// 注意：期货接口 interval 定义: 1, 5, 15, 30, 60, 1dconstklineUrl=`${BASE_URL}/futures/kline?symbol=${symbol}&interval=1d&key=${API_KEY}`;try{constres=awaitfetch(klineUrl);constjson=awaitres.json();if(json.code===200&&json.data){// 转换数据格式// 期货接口返回: date (字符串时间), open, close, high, low, volume, timestamp (秒级)constdataList=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>
