美股 (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);