@itick/node-sdk

v1.0.3

Published

2 hours ago

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

0High
0Medium
0Low

itick100

qq1648437631

iTick Financial API Market Data API Stock API Forex API Crypto API Real-time Quotes Historical Data OHLCV K-line WebSocket API REST API Quantitative Trading

English | 簡體中文 | 繁體中文

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

✨ 特性

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

🚀 安裝

npm install @itick/node-sdk

環境要求：

Node.js >= 18.0.0

🎯 快速開始

基礎用法

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 獲取實時數據

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 參考

基礎模組

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

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 方法參考表

股票模組

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

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 方法參考表

加密貨幣模組

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

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 方法參考表

外匯模組

訪問外匯市場數據。

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 方法參考表

指數模組

訪問全球股票指數數據。

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 方法參考表

期貨模組

訪問期貨市場數據。

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 方法參考表

基金模組

訪問共同基金和 ETF 數據。

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 方法參考表

🔌 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：月線

連接選項

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

事件處理器

// 連接打開
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();

動態訂閱

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

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

⚠️ 錯誤處理

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 支持和全面的類型定義：

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 文檔 - 完整的 API 參考
REST API 指南 - 詳細的 REST 端點
WebSocket 指南 - 實時數據流
GitHub 倉庫 - 源代碼和問題反饋

📄 許可證

MIT 許可證 - 查看 LICENSE 文件了解詳情。

🤝 貢獻

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

📧 支持

網站：https://itick.org
郵箱：[email protected]
問題反饋：GitHub Issues

由 iTick 團隊用 ❤️ 製作