美股 (US) 与 墨西哥 (Mexico) 股票数据接口集成指南

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);