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：

2. 核心數據接口

2.1 獲取股票列表 (Stock List)

用於查詢指定市場的股票清單，獲取股票的名稱、代碼 (Symbol) 和 系統 ID (PID)。

注意：id (PID) 是後續查詢 K 線和訂閲 WebSocket 的唯一標識符。

• 接口地址: /stock/stocks
• 請求方式: GET
• 請求參數:

• 請求示例 (獲取美股列表):

  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
• 請求參數:

• 週期 (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);