1. 接入概述 (General)
本接口用于获取美国（NYSE, NASDAQ, AMEX）及墨西哥（BMV, BIVA）证券市场的实时行情、历史 K 线及指数数据。
- API Base URL:
https://api.stocktv.top - WebSocket URL:
wss://ws-api.stocktv.top/connect - 鉴权方式: 所有请求均需携带 URL 参数
key=您的API密钥
1.1 关键市场 ID (Country ID)
在调用相关接口时，请务必区分以下 countryId：
| 市场名称 | Country ID | 交易所示例 |
|---|---|---|
| 美国 (USA) | 5 | NYSE (1), NASDAQ (2), AMEX |
| 墨西哥 (Mexico) | 7 | Mexico (53), BIVA (144) |
2. 核心数据接口
2.1 获取股票列表 (Stock List)
用于查询指定市场的股票清单，获取股票的名称、代码 (Symbol) 和 系统 ID (PID)。
注意：
id(PID) 是后续查询 K 线和订阅 WebSocket 的唯一标识符。
- 接口地址:
/stock/stocks - 请求方式:
GET - 请求参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
key |
String | 是 | 您的 API Key |
countryId |
Int | 是 | 5 (美股) 或 7 (墨西哥) |
pageSize |
Int | 否 | 每页数量 (默认 10) |
page |
Int | 否 | 页码 (默认 1) |
-
请求示例 (获取美股列表):
GET https://api.stocktv.top/stock/stocks?countryId=5&pageSize=20&page=1&key=YOUR_KEY -
响应示例:
{"code": 200,"data": {"records": [{"id": 8888, // [关键] PID，用于K线接口"name": "Apple Inc", // 股票名称"symbol": "AAPL", // 股票代码"exchangeId": 2, // 交易所ID (2=NASDAQ)"last": 180.5, // 最新价"chgPct": 1.25, // 涨跌幅%"countryNameTranslated": "United States"}]} }
2.2 获取 K 线数据 (Candlestick Data)
获取指定股票的历史行情数据，支持多种时间周期。
- 接口地址:
/stock/kline - 请求方式:
GET - 请求参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
key |
String | 是 | 您的 API Key |
pid |
Int | 是 | 股票系统 ID (通过 2.1 接口获取) |
interval |
String | 是 | K线周期 (ISO 8601格式) |
-
周期 (Interval) 说明:
PT1M(1分钟),PT5M(5分钟),PT15M(15分钟),PT30M(30分钟),PT1H(1小时)P1D(日线),P1W(周线),P1M(月线)
-
请求示例 (获取墨西哥某股票日线):
GET https://api.stocktv.top/stock/kline?pid=12345&interval=P1D&key=YOUR_KEY -
响应示例:
{"code": 200,"data": [{"time": 1719818400000, // 时间戳 (毫秒)"open": 150.0,"high": 155.0,"low": 149.0,"close": 153.0,"volume": 200000}] }
2.3 获取大盘指数 (Indices)
获取美股（如纳斯达克、标普500）或墨西哥（如 S&P/BMV IPC）的指数行情。
-
接口地址:
/stock/indices -
请求方式:
GET -
请求参数:
countryId(5=美国, 7=墨西哥) -
请求示例:
GET https://api.stocktv.top/stock/indices?countryId=7&key=YOUR_KEY
3. WebSocket 实时推送
通过 WebSocket 长连接接收实时报价更新。
- 连接地址:
wss://ws-api.stocktv.top/connect?key=YOUR_KEY - 心跳机制: 连接建立后，建议定期发送心跳包以保持连接。
- 推送数据结构:
{"pid": "8888", // 对应 Rest API 中的 id"last_numeric": 181.2, // 最新价"pcp": "0.39", // 涨跌幅%"timestamp": "1717728251","bid": "181.1", // 买价"ask": "181.3", // 卖价"type": 1 // 1=股票, 2=指数 }
4. 接入代码示例 (JavaScript)
以下代码展示了如何根据 countryId 封装获取美股和墨西哥股票的逻辑。
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.stocktv.top';// 配置 ID
const MARKETS = {USA: 5,MEXICO: 7
};/*** 获取指定市场的股票列表* @param {number} countryId - 5 for USA, 7 for Mexico*/
async function getMarketStocks(countryId) {const url = `${BASE_URL}/stock/stocks?countryId=${countryId}&pageSize=10&page=1&key=${API_KEY}`;try {const response = await fetch(url);const result = await response.json();if (result.code === 200) {console.log(`市场 (ID:${countryId}) 股票列表:`, result.data.records);// 示例：获取第一个股票的 PID 用于查 K 线if(result.data.records.length > 0) {const firstStock = result.data.records[0];console.log(`示例股票: ${firstStock.name}, PID: ${firstStock.id}`);}}} catch (error) {console.error('API 请求失败:', error);}
}// 1. 获取美股数据
getMarketStocks(MARKETS.USA);// 2. 获取墨西哥股票数据
getMarketStocks(MARKETS.MEXICO);
