npm package: @itick/node-sdk
Description: Official iTick API SDK for Node.js. Real-time & historical data for global Stocks, Forex, Crypto, Indices, Futures, Funds, Precious Metals. REST (OHLCV/K-line) + low-latency WebSocket. Promise-based, TypeScript-ready. For quant trading & fintech
Author: iTick
Latest version: 1.0.2

<!-- markdownlint-disable no-inline-html first-line-h1 -->
<div align="center">
    <img src="https://itick.org/img/apple.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/alphabet.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/microsoft.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/icon/us-nasdaq-tsla.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/icon/us-nasdaq-nvda.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/crypto/XTVCBTC.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/crypto/XTVCETH.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/crypto/XTVCUSDT.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/crypto/XTVCSHIB.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/indices/s-and-p-500.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/indices/nasdaq-100.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/indices/hang-seng.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/indices/nikkei-225.svg" style="border-radius: 50%;margin-right: 6px;" />
    <img src="https://itick.org/img/metal/gold.svg" style="border-radius: 50%;margin-right: 6px;" />
  </div>

<div align="center">
  <a href="https://itick.org" target="_blank" style="display: flex;justify-content: center;margin-top: 20px;">
    <img width="400" src="https://itick.org/images/logo/logo.svg" alt="iTick logo">
  </a>
  
  <h1>iTick Node.js SDK</h1>

[![npm version][npm-version-img]][npm-link]
[![node version][node-version-img]][node-version-link]
[![install size][npm-install-size-img]][npm-install-size-link]
[![npm bundle size][bundle-size-img]][bundle-size-link]
[![npm peer dependency][npm-peer-dependency-img]][npm-peer-dependency-link]
[![license badge][license-img]][license-link]

</div>

<!-- markdownlint-enable no-inline-html -->

[English](https://github.com/itick-org/nodejs-sdk/blob/main/README.md) | [簡體中文](https://github.com/itick-org/nodejs-sdk/blob/main/README.zh-CN.md) | [繁體中文](https://github.com/itick-org/nodejs-sdk/blob/main/README.zh-HK.md) 

Node.js 版本的 iTick API SDK，提供基礎、股票、指數、期貨、基金、外匯、加密貨幣數據的 REST API 查詢和 WebSocket 實時數據訂閱功能。用於訪問 iTick API 的實時金融市場數據。

## ✨ 特性

- **全面的市場覆蓋**：訪問全球金融市場，包括股票、加密貨幣、外匯、指數、期貨和基金
- **實時數據**：基於 WebSocket 的實時數據流，支持自動重連
- **RESTful API**：簡潔直觀的 REST API，用於獲取歷史數據和快照
- **類型安全**：完整的 TypeScript 支持和全面的類型定義
- **自動重連**：內置自動重連機制（5 秒間隔，可設置無限次嘗試）
- **心跳保活**：自動 ping/pong 機制（30 秒間隔）保持連接穩定
- **模組化設計**：按資產類型劃分獨立模組，結構更清晰
- **靈活訂閱**：支持報價、盤口、成交和 K 線數據訂閱

## 🚀 安裝

```bash
npm install @itick/node-sdk
```

**環境要求：**

- Node.js >= 18.0.0

## 🎯 快速開始

### 基礎用法

```javascript
import { StockClient } from "@itick/node-sdk";

// 使用 API Token 初始化客戶端
const token = process.env.ITICK_TOKEN;
const client = new StockClient(token);

// 獲取股票報價
async function getQuote() {
  try {
    const response = await client.getQuote({ region: "US", code: "AAPL" });

    if (response.code === 0 && response.data) {
      console.log("最新價格:", response.data.ld);
      console.log("漲跌幅:", response.data.chp);
    }
  } catch (error) {
    console.error("錯誤:", error.message);
  }
}

getQuote();
```

### 通過 WebSocket 獲取實時數據

```javascript
import { CryptoClient } from "@itick/node-sdk";
const client = new CryptoClient(token);

// 創建帶訂閱數據的 WebSocket 連接 SDK內部已處理連接和重連後直接訂閱 subscribeData 數據 無需再發送訂閱數據
const socket = client.createSocket({
  maxReconnectTimes: 10, // 最大重連次數 不傳則使用默認值 0 無限制重連
  pingInterval: 30000, // ping 間隔 默認30 秒
  reconnectInterval: 5000, // 重連間隔 默認5 秒
  subscribeData: {
    codes: ["BTCUSDT$BA", "ETHUSDT$BA"],
    types: ["quote", "tick"],
  },
});

// 創建自定義 WebSocket 連接
const socket = client.createSocket();

// 連接成功或者重連連成功後發送訂閱數據
socket.onSocketOpen(() => {
  socket.subscribeData({
    codes: ["BTCUSDT$BA", "ETHUSDT$BA"],
    types: ["quote", "tick"],
  });
});

// 處理接收到的消息
socket.onSocketMessage((res) => {
  console.log("收到數據:", res);
});

// 處理錯誤
socket.onSocketError((error) => {
  console.error("WebSocket 錯誤:", error);
});

// 完成後斷開連接
// socket.disconnectSocket();
```

## 📚 API 參考

### 基礎模組

金融產品清單和市場節假日信息以及開市休市時間信息。

```typescript
import { BaseClient } from "@itick/node-sdk";

const client = new BaseClient(token);

// 獲取值種列表
await client.getSymbolList({ type: "stock", region: "US" });
await client.getSymbolList({ type: "crypto", region: "BA" });
await client.getSymbolList({ type: "forex", region: "GB" });

// 獲取市場假期
await client.getSymbolHolidays("US");
await client.getSymbolHolidays("HK");
```

#### BaseClient 方法參考表

| 方法名              | 參數說明                                                                                                                                                       | 返回值類型                               | 描述                                               | 詳細參數                                                                 |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :------------------------------------------------- | :----------------------------------------------------------------------- |
| `getSymbolList`     | `options`: `Object`<br>- `type`:`enum` (產品類型，如 `stock`,`forex`,`fund`,`future`,`indices`) <br>- `region`:`string` (市場區域代碼，如 `US`, `BA`, `GB` 等) | `Promise<APIResponse<SymbolListData[]>>` | 獲取指定市場和資產類型的金融產品清單（品種列表）。 | [iTick 產品清單](https://docs.itick.org/rest-api/basics/symbol-list)     |
| `getSymbolHolidays` | region: `string` (市場區域代碼，如 `US`, `HK` 等)                                                                                                              | `Promise<APIResponse<HolidayData[]>>`    | 獲取指定市場的節假日信息，包括開市和休市時間安排。 | [iTick 市場假期](https://docs.itick.org/rest-api/basics/symbol-holidays) |

### 股票模組

訪問美股、港股等全球股票市場數據。

```javascript
import { StockClient } from "@itick/node-sdk";

const client = new StockClient(token);

// 獲取單只股票信息
await client.getInfo({ region: "US", code: "AAPL" });

// 獲取實時報價
await client.getQuote({ region: "US", code: "AAPL" });

// 獲取盤口深度
await client.getDepth({ region: "US", code: "AAPL" });

// 獲取最新成交
await client.getTick({ region: "US", code: "AAPL" });

// 獲取 K 線數據
await client.getKline({
  region: "US",
  code: "AAPL",
  interval: "5m",
  limit: 100,
});

// 批量查詢
await client.getQuotes({ region: "US", codes: ["AAPL", "MSFT", "GOOGL"] });
await client.getDepths({ region: "US", codes: ["AAPL", "MSFT"] });
await client.getTicks({ region: "US", codes: ["AAPL", "MSFT"] });
await client.getKlines({
  region: "US",
  codes: ["AAPL", "MSFT"],
  interval: "1d",
  limit: 50,
});

// IPO 信息
await client.getIPO({ region: "US", code: "RIVN" });

// 調整係數| 除權因子
await client.getSplit({ region: "US", code: "AAPL" });
```

#### StockClient 方法參考表

| 方法名 | 參數說明 | 返回值類型 | 描述 | 詳細參數 |
| :--- | :--- | :--- | :--- | :--- |
| `getInfo` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (股票代碼，如 `AAPL`) | `Promise<APIResponse<StockInfo>>` | 獲取股票基本信息 | [iTick 股票信息](https://docs.itick.org/rest-api/stocks/stock-info) |
| `getIPO` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (股票代碼，如 `AAPL`) | `Promise<APIResponse<StockIPO>>` | 獲取股票 IPO 信息 | [iTick 股票 IPO](https://docs.itick.org/rest-api/stocks/stock-ipo) |
| `getSplit` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (股票代碼，如 `AAPL`) | `Promise<APIResponse<StockSplit>>` | 獲取股票除權因子調整係數 | [iTick 股票除權因子](https://docs.itick.org/rest-api/stocks/stock-split) |
| `getTick` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (股票代碼，如 `AAPL`) | `Promise<APIResponse<TickData>>` | 獲取單個股票最新成交行情 | [iTick 股票實時成交](https://docs.itick.org/rest-api/stocks/stock-tick) |
| `getQuote` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (股票代碼，如 `AAPL`) | `Promise<APIResponse<QuoteData>>` | 獲取單個股票最新報價 | [iTick 股票實時報價](https://docs.itick.org/rest-api/stocks/stock-quote) |
| `getDepth` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (股票代碼，如 `AAPL`) | `Promise<APIResponse<DepthData>>` | 獲取單個股票最新盤口 | [iTick 股票實時盤口](https://docs.itick.org/rest-api/stocks/stock-depth) |
| `getKline`   | `options`: `GetKlineOptions`<br>- `region`: `string` (市場編碼)<br>- `code`: `string` (股票代碼)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineData[]>>` | 獲取單個股票 K 線數據 | [iTick 股票 K 線](https://docs.itick.org/rest-api/stocks/stock-kline) |
| `getTicks` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (股票代碼列表) | `Promise<APIResponse<TickDataMap>>` | 獲取多個股票最新成交行情 | [iTick 股票批量成交](https://docs.itick.org/rest-api/stocks/stock-ticks) |
| `getQuotes` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (股票代碼列表) | `Promise<APIResponse<QuoteDataMap>>` | 獲取多個股票最新報價 | [iTick 股票批量報價](https://docs.itick.org/rest-api/stocks/stock-quotes) |
| `getDepths` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (股票代碼列表) | `Promise<APIResponse<DepthDataMap>>` | 獲取多個股票最新盤口 | [iTick 股票批量盤口](https://docs.itick.org/rest-api/stocks/stock-depths) |
| `getKline` | `options`: `GetKlinesOptions`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (股票代碼列表)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineDataMap>>` | 獲取多個股票 K 線數據 | [iTick 股票批量 K 線](https://docs.itick.org/rest-api/stocks/stock-klines) |
| `createSocket` | `options`?: `CreateSocketOptions` (可選，WebSocket 連接選項) | `SocketClient` | 創建 WebSocket 連接用於實時數據訂閱 | [iTick WebSocket 股票](https://docs.itick.org/websocket/stocks) |

### 加密貨幣模組

訪問多個交易所的加密貨幣市場數據。

```javascript
import { CryptoClient } from "@itick/node-sdk";

const client = new CryptoClient(token);

// 獲取實時數據
await client.getQuote({ region: "BA", code: "BTCUSDT" });
await client.getDepth({ region: "BA", code: "ETHUSDT" });
await client.getTick({ region: "BA", code: "BTCUSDT" });

// 獲取 K 線數據
await client.getKline({
  region: "BA",
  code: "BTCUSDT",
  interval: "1h",
  limit: 100,
});

// 批量查詢
await client.getQuotes({ region: "BA", codes: ["BTCUSDT", "ETHUSDT"] });
```

#### CryptoClient 方法參考表

| 方法名 | 參數說明 | 返回值類型 | 描述 | 詳細參數 |
| :--- | :--- | :--- | :--- | :--- |
| `getTick` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `BA`, `BT`, `PB` 等)<br>- `code`: `string` (標的代碼，如 `BTCUSDT`) | `Promise<APIResponse<TickData>>` | 獲取單個加密貨幣最新成交行情 | [iTick 加密貨幣實時成交](https://docs.itick.org/rest-api/crypto/crypto-tick) |
| `getQuote` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `BA`, `BT`, `PB` 等)<br>- `code`: `string` (標的代碼，如 `BTCUSDT`) | `Promise<APIResponse<QuoteData>>` | 獲取單個加密貨幣最新報價 | [iTick 加密貨幣實時報價](https://docs.itick.org/rest-api/crypto/crypto-quote) |
| `getDepth` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `BA`, `BT`, `PB` 等)<br>- `code`: `string` (標的代碼，如 `BTCUSDT`) | `Promise<APIResponse<DepthData>>` | 獲取單個加密貨幣最新盤口 | [iTick 加密貨幣實時盤口](https://docs.itick.org/rest-api/crypto/crypto-depth) |
| `getKline`   | `options`: `GetKlineOptions`<br>- `region`: `string` (市場編碼)<br>- `code`: `string` (標的代碼)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineData[]>>` | 獲取單個加密貨幣 K 線數據 | [iTick 加密貨幣 K 線](https://docs.itick.org/rest-api/crypto/crypto-kline) |
| `getTicks` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<TickDataMap>>` | 獲取多個加密貨幣最新成交行情 | [iTick 加密貨幣批量成交](https://docs.itick.org/rest-api/crypto/crypto-ticks) |
| `getQuotes` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<QuoteDataMap>>` | 獲取多個加密貨幣最新報價 | [iTick 加密貨幣批量報價](https://docs.itick.org/rest-api/crypto/crypto-quotes) |
| `getDepths` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<DepthDataMap>>` | 獲取多個加密貨幣最新盤口 | [iTick 加密貨幣批量盤口](https://docs.itick.org/rest-api/crypto/crypto-depths) |
| `getKline` | `options`: `GetKlinesOptions`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineDataMap>>` | 獲取多個加密貨幣 K 線數據 | [iTick 加密貨幣批量 K 線](https://docs.itick.org/rest-api/crypto/crypto-klines) |
| `createSocket` | `options`?: `CreateSocketOptions` (可選，WebSocket 連接選項) | `SocketClient` | 創建 WebSocket 連接用於實時數據訂閱 | [iTick WebSocket 加密貨幣](https://docs.itick.org/websocket/crypto) |

### 外匯模組

訪問外匯市場數據。

```javascript
import { ForexClient } from "@itick/node-sdk";

const client = new ForexClient(token);

await client.getQuote({ region: "GB", code: "EURUSD" });
await client.getDepth({ region: "GB", code: "GBPUSD" });
await client.getTick({ region: "GB", code: "USDJPY" });
await client.getKline({ region: "GB", code: "EURUSD", interval: "1d", limit: 50 });
```

#### ForexClient 方法參考表

| 方法名 | 參數說明 | 返回值類型 | 描述 | 詳細參數 |
| :--- | :--- | :--- | :--- | :--- |
| `getTick` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `GB` 等)<br>- `code`: `string` (標的代碼，如 `EURUSD`) | `Promise<APIResponse<TickData>>` | 獲取單個外匯對最新成交行情 | [iTick 外匯實時成交](https://docs.itick.org/rest-api/forex/forex-tick) |
| `getQuote` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `GB` 等)<br>- `code`: `string` (標的代碼，如 `EURUSD`) | `Promise<APIResponse<QuoteData>>` | 獲取單個外匯對最新報價 | [iTick 外匯實時報價](https://docs.itick.org/rest-api/forex/forex-quote) |
| `getDepth` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `GB` 等)<br>- `code`: `string` (標的代碼，如 `EURUSD`) | `Promise<APIResponse<DepthData>>` | 獲取單個外匯對最新盤口 | [iTick 外匯實時盤口](https://docs.itick.org/rest-api/forex/forex-depth) |
| `getKline`   | `options`: `GetKlineOptions`<br>- `region`: `string` (市場編碼)<br>- `code`: `string` (標的代碼)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineData[]>>` | 獲取單個外匯對 K 線數據 | [iTick 外匯 K 線](https://docs.itick.org/rest-api/forex/forex-kline) |
| `getTicks` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<TickDataMap>>` | 獲取多個外匯對最新成交行情 | [iTick 外匯批量成交](https://docs.itick.org/rest-api/forex/forex-ticks) |
| `getQuotes` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<QuoteDataMap>>` | 獲取多個外匯對最新報價 | [iTick 外匯批量報價](https://docs.itick.org/rest-api/forex/forex-quotes) |
| `getDepths` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<DepthDataMap>>` | 獲取多個外匯對最新盤口 | [iTick 外匯批量盤口](https://docs.itick.org/rest-api/forex/forex-depths) |
| `getKline` | `options`: `GetKlinesOptions`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineDataMap>>` | 獲取多個外匯對 K 線數據 | [iTick 外匯批量 K 線](https://docs.itick.org/rest-api/forex/forex-klines) |
| `createSocket` | `options`?: `CreateSocketOptions` (可選，WebSocket 連接選項) | `SocketClient` | 創建 WebSocket 連接用於實時數據訂閱 | [iTick WebSocket 外匯](https://docs.itick.org/websocket/forex) |

### 指數模組

訪問全球股票指數數據。

```javascript
import { IndicesClient } from "@itick/node-sdk";

const client = new IndicesClient(token);

await client.getQuote({ region: "US", code: "SPX" });
await client.getDepth({ region: "US", code: "NDX" });
await client.getKline({ region: "US", code: "DJI", interval: "1w", limit: 20 });
```

#### IndicesClient 方法參考表

| 方法名 | 參數說明 | 返回值類型 | 描述 | 詳細參數 |
| :--- | :--- | :--- | :--- | :--- |
| `getTick` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `GB` 等)<br>- `code`: `string` (標的代碼，如 `DJI`, `SPX`) | `Promise<APIResponse<TickData>>` | 獲取單個指數最新成交行情 | [iTick 指數實時成交](https://docs.itick.org/rest-api/indices/indices-tick) |
| `getQuote` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `GB` 等)<br>- `code`: `string` (標的代碼，如 `DJI`, `SPX`) | `Promise<APIResponse<QuoteData>>` | 獲取單個指數最新報價 | [iTick 指數實時報價](https://docs.itick.org/rest-api/indices/indices-quote) |
| `getDepth` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `GB` 等)<br>- `code`: `string` (標的代碼，如 `DJI`, `SPX`) | `Promise<APIResponse<DepthData>>` | 獲取單個指數最新盤口 | [iTick 指數實時盤口](https://docs.itick.org/rest-api/indices/indices-depth) |
| `getKline`   | `options`: `GetKlineOptions`<br>- `region`: `string` (市場編碼)<br>- `code`: `string` (標的代碼)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineData[]>>` | 獲取單個指數 K 線數據 | [iTick 指數 K 線](https://docs.itick.org/rest-api/indices/indices-kline) |
| `getTicks` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<TickDataMap>>` | 獲取多個指數最新成交行情 | [iTick 指數批量成交](https://docs.itick.org/rest-api/indices/indices-ticks) |
| `getQuotes` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<QuoteDataMap>>` | 獲取多個指數最新報價 | [iTick 指數批量報價](https://docs.itick.org/rest-api/indices/indices-quotes) |
| `getDepths` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<DepthDataMap>>` | 獲取多個指數最新盤口 | [iTick 指數批量盤口](https://docs.itick.org/rest-api/indices/indices-depths) |
| `getKline` | `options`: `GetKlinesOptions`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineDataMap>>` | 獲取多個指數 K 線數據 | [iTick 指數批量 K 線](https://docs.itick.org/rest-api/indices/indices-klines) |
| `createSocket` | `options`?: `CreateSocketOptions` (可選，WebSocket 連接選項) | `SocketClient` | 創建 WebSocket 連接用於實時數據訂閱 | [iTick WebSocket 指數](https://docs.itick.org/websocket/indices) |

### 期貨模組

訪問期貨市場數據。

```javascript
import { FutureClient } from "@itick/node-sdk";

const client = new FutureClient(token);

await client.getQuote({ region: "US", code: "ES" });
await client.getDepth({ region: "US", code: "NQ" });
await client.getKline({ region: "US", code: "CL", interval: "5m", limit: 100 });
```

#### FutureClient 方法參考表

| 方法名 | 參數說明 | 返回值類型 | 描述 | 詳細參數 |
| :--- | :--- | :--- | :--- | :--- |
| `getTick` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `CN`, `HK` 等)<br>- `code`: `string` (標的代碼，如 `CL`, `GC`) | `Promise<APIResponse<TickData>>` | 獲取單個期貨合約最新成交行情 | [iTick 期貨實時成交](https://docs.itick.org/rest-api/future/future-tick) |
| `getQuote` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `CN`, `HK` 等)<br>- `code`: `string` (標的代碼，如 `CL`, `GC`) | `Promise<APIResponse<QuoteData>>` | 獲取單個期貨合約最新報價 | [iTick 期貨實時報價](https://docs.itick.org/rest-api/future/future-quote) |
| `getDepth` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `CN`, `HK` 等)<br>- `code`: `string` (標的代碼，如 `CL`, `GC`) | `Promise<APIResponse<DepthData>>` | 獲取單個期貨合約最新盤口 | [iTick 期貨實時盤口](https://docs.itick.org/rest-api/future/future-depth) |
| `getKline`   | `options`: `GetKlineOptions`<br>- `region`: `string` (市場編碼)<br>- `code`: `string` (標的代碼)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineData[]>>` | 獲取單個期貨合約 K 線數據 | [iTick 期貨 K 線](https://docs.itick.org/rest-api/future/future-kline) |
| `getTicks` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<TickDataMap>>` | 獲取多個期貨合約最新成交行情 | [iTick 期貨批量成交](https://docs.itick.org/rest-api/future/future-ticks) |
| `getQuotes` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<QuoteDataMap>>` | 獲取多個期貨合約最新報價 | [iTick 期貨批量報價](https://docs.itick.org/rest-api/future/future-quotes) |
| `getDepths` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<DepthDataMap>>` | 獲取多個期貨合約最新盤口 | [iTick 期貨批量盤口](https://docs.itick.org/rest-api/future/future-depths) |
| `getKline` | `options`: `GetKlinesOptions`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineDataMap>>` | 獲取多個期貨合約 K 線數據 | [iTick 期貨批量 K 線](https://docs.itick.org/rest-api/future/future-klines) |
| `createSocket` | `options`?: `CreateSocketOptions` (可選，WebSocket 連接選項) | `SocketClient` | 創建 WebSocket 連接用於實時數據訂閱 | [iTick WebSocket 期貨](https://docs.itick.org/websocket/future) |

### 基金模組

訪問共同基金和 ETF 數據。

```javascript
import { FundClient } from "@itick/node-sdk";

const client = new FundClient(token);

await client.getQuote({ region: "US", code: "VOO" });
await client.getDepth({ region: "US", code: "QQQ" });
await client.getKline({ region: "US", code: "SPY", interval: "1d", limit: 100 });
```

#### FundClient 方法參考表

| 方法名 | 參數說明 | 返回值類型 | 描述 | 詳細參數 |
| :--- | :--- | :--- | :--- | :--- |
| `getTick` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (標的代碼，如 `SPY`, `QQQ`) | `Promise<APIResponse<TickData>>` | 獲取單個基金最新成交行情 | [iTick 基金實時成交](https://docs.itick.org/rest-api/fund/fund-tick) |
| `getQuote` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (標的代碼，如 `SPY`, `QQQ`) | `Promise<APIResponse<QuoteData>>` | 獲取單個基金最新報價 | [iTick 基金實時報價](https://docs.itick.org/rest-api/fund/fund-quote) |
| `getDepth` | `params`: `Object`<br>- `region`: `string` (市場編碼，如 `US`, `HK` 等)<br>- `code`: `string` (標的代碼，如 `SPY`, `QQQ`) | `Promise<APIResponse<DepthData>>` | 獲取單個基金最新盤口 | [iTick 基金實時盤口](https://docs.itick.org/rest-api/fund/fund-depth) |
| `getKline`   | `options`: `GetKlineOptions`<br>- `region`: `string` (市場編碼)<br>- `code`: `string` (標的代碼)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineData[]>>` | 獲取單個基金 K 線數據 | [iTick 基金 K 線](https://docs.itick.org/rest-api/fund/fund-kline) |
| `getTicks` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<TickDataMap>>` | 獲取多個基金最新成交行情 | [iTick 基金批量成交](https://docs.itick.org/rest-api/fund/fund-ticks) |
| `getQuotes` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<QuoteDataMap>>` | 獲取多個基金最新報價 | [iTick 基金批量報價](https://docs.itick.org/rest-api/fund/fund-quotes) |
| `getDepths` | `params`: `Object`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表) | `Promise<APIResponse<DepthDataMap>>` | 獲取多個基金最新盤口 | [iTick 基金批量盤口](https://docs.itick.org/rest-api/fund/fund-depths) |
| `getKline` | `options`: `GetKlinesOptions`<br>- `region`: `string` (市場編碼)<br>- `codes`: `string[] \| string` (標的代碼列表)<br>- `interval`: `KlineType` (K 線週期類型)<br>- `limit`: `number` (返回數據條數，最大 500)<br>- `et`?: `string \| number` (可選，結束時間戳) | `Promise<APIResponse<KlineDataMap>>` | 獲取多個基金 K 線數據 | [iTick 基金批量 K 線](https://docs.itick.org/rest-api/fund/fund-klines) |
| `createSocket` | `options`?: `CreateSocketOptions` (可選，WebSocket 連接選項) | `SocketClient` | 創建 WebSocket 連接用於實時數據訂閱 | [iTick WebSocket 基金](https://docs.itick.org/websocket/fund) |

## 🔌 WebSocket 實時數據

### 支持的數據類型

- `quote`：實時報價
- `depth`：盤口深度
- `tick`：最新成交
- `kline@1m` 或 `kline@1`：1 分鐘 K 線
- `kline@5m` 或 `kline@2`：5 分鐘 K 線
- `kline@15m` 或 `kline@3`：15 分鐘 K 線
- `kline@30m` 或 `kline@4`：30 分鐘 K 線
- `kline@1h` 或 `kline@5`：1 小時 K 線
- `kline@2h` 或 `kline@6`：2 小時 K 線（僅加密貨幣）
- `kline@4h` 或 `kline@7`：4 小時 K 線（僅加密貨幣）
- `kline@1d` 或 `kline@8`：日線
- `kline@1w` 或 `kline@9`：周線
- `kline@1M` 或 `kline@10`：月線

### 連接選項

```typescript
const socket = client.createSocket({
  maxReconnectTimes: 10, // 最大重連次數（0 = 無限）
  reconnectInterval: 5000, // 重連間隔（毫秒）
  pingInterval: 30000, // Ping 間隔（毫秒）
  subscribeData: {
    codes: ["AAPL$US", "MSFT$US"],
    types: ["quote", "tick", "kline@1m"],
  },
});
```

### 事件處理器

```javascript
// 連接打開
socket.onSocketOpen(() => {
  console.log("已連接！");
});

// 接收消息
socket.onSocketMessage((data) => {
  console.log("收到數據:", data);
});

// 發生錯誤
socket.onSocketError((error) => {
  console.error("錯誤:", error);
});

// 連接關閉
socket.onSocketClose(() => {
  console.log("已斷開");
});

// 檢查連接狀態
const isConnected = socket.checkSocketConnected();

// 斷開連接
socket.disconnectSocket();
```

### 動態訂閱

```javascript
// 連接後訂閱
socket.subscribeSocket({
  ac: "subscribe",
  types: ["quote", "depth"],
  codes: ["TSLA$US", "NVDA$US"],
});

// 取消訂閱
socket.subscribeSocket({
  ac: "unsubscribe",
  types: ["tick"],
  codes: ["AAPL$US"],
});
```

## ⚠️ 錯誤處理

```javascript
try {
  const response = await client.getQuote({ region: "US", code: "AAPL" });

  if (response.code !== 0) {
    console.error("API 錯誤:", response.msg);
    return;
  }

  // 處理數據
  console.log(response.data);
} catch (error) {
  if (error instanceof Error) {
    console.error("網絡錯誤:", error.message);
  }
}
```

## 📘 TypeScript 支持

完整的 TypeScript 支持和全面的類型定義：

```javascript
import type {
  APIResponse,
  QuoteData,
  SocketKlineData,
  SocketTickData,
  SocketDepthData,
  SocketQuoteData,
} from "@itick/node-sdk";

// 類型安全的響應
const response: APIResponse<QuoteData> = await client.getQuote({
  region: "US",
  code: "AAPL",
});

// 類型安全的 WebSocket 消息
socket.onSocketMessage((response) => {
  const { code, data, msg, resAc } = response;
  if (data?.type === "quote") {
    const quoteData: SocketQuoteData = data;
  }
  if (data?.type === "kline@1") {
    const klineData: SocketKlineData = data;
  }
  if (data?.type === "tick") {
    const tickData: SocketTickData = data;
  }
  if (data?.type === "depth") {
    const depthData: SocketDepthData = data;
  }
});
```

## 📖 文檔

- **[官方 API 文檔](https://docs.itick.org)** - 完整的 API 參考
- **[REST API 指南](https://docs.itick.org/rest-api)** - 詳細的 REST 端點
- **[WebSocket 指南](https://docs.itick.org/websocket)** - 實時數據流
- **[GitHub 倉庫](https://github.com/itick-org/nodejs-sdk)** - 源代碼和問題反饋

## 📄 許可證

MIT 許可證 - 查看 [LICENSE](LICENSE) 文件了解詳情。

## 🤝 貢獻

歡迎貢獻！請隨時提交 Pull Request。

## 📧 支持

- **網站**：[https://itick.org](https://itick.org)
- **郵箱**：support@itick.org
- **問題反饋**：[GitHub Issues](https://github.com/itick-org/nodejs-sdk/issues)

---

由 iTick 團隊用 ❤️ 製作

[npm-version-img]: https://img.shields.io/npm/v/@itick/node-sdk
[npm-link]: https://www.npmjs.com/package/@itick/node-sdk
[node-version-img]: https://img.shields.io/node/v/@itick/node-sdk
[node-version-link]: https://nodejs.org/
[npm-install-size-img]: https://packagephobia.now.sh/badge?p=@itick/node-sdk
[npm-install-size-link]: https://packagephobia.now.sh/result?p=@itick/node-sdk
[bundle-size-img]: https://img.shields.io/bundlephobia/minzip/@itick/node-sdk
[bundle-size-link]: https://bundlephobia.com/package/@itick/node-sdk@latest
[npm-peer-dependency-img]: https://img.shields.io/badge/dynamic/json?label=dependencies&color=brightgreen&query=$.dependencyCount&url=https://bundlephobia.com/api/size?package=@itick/node-sdk
[npm-peer-dependency-link]: https://bundlephobia.com/package/@itick/node-sdk
[license-img]: https://img.shields.io/npm/l/@itick/node-sdk
[license-link]: https://opensource.org/licenses/MIT