> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/sdk-and-tools/nodejs-sdk.md).

# Node.js SDK

### 概述

Infoway 官方 Node.js/TypeScript SDK，提供完整的 REST API 和 WebSocket 实时推送接口，全面的 TypeScript 类型定义。

| 项目         | 说明                                                                                  |
| ---------- | ----------------------------------------------------------------------------------- |
| npm        | [`infoway-sdk`](https://www.npmjs.com/package/infoway-sdk)                          |
| Node.js 版本 | 18+                                                                                 |
| 协议         | MIT                                                                                 |
| GitHub     | [infoway-api/infoway-sdk-nodejs](https://github.com/infoway-api/infoway-sdk-nodejs) |

### 安装

```bash
npm install infoway-sdk
# 或
yarn add infoway-sdk
# 或
pnpm add infoway-sdk
```

### 快速开始

```typescript
import { InfowayClient, KlineType } from "infoway-sdk";

const client = new InfowayClient({ apiKey: "YOUR_API_KEY" });

// 股票实时行情
const trades = await client.stock.getTrade("AAPL.US");

// 多个标的同时查询
const multiTrades = await client.stock.getTrade("AAPL.US,TSLA.US,GOOGL.US");

// 买卖盘口
const depth = await client.stock.getDepth("AAPL.US");

// K线数据
const klines = await client.stock.getKline("AAPL.US", KlineType.DAY, 100);

// 加密货币
const btc = await client.crypto.getTrade("BTCUSDT");

// 市场温度
const temp = await client.market.getTemperature("HK,US");

// 个股基本面
const valuation = await client.stockInfo.getValuation("AAPL.US");

// 板块数据
const industries = await client.plate.getIndustry("HK");
```

### 配置

```bash
export INFOWAY_API_KEY="YOUR_API_KEY"
```

```typescript
// 自动读取环境变量 INFOWAY_API_KEY
const client = new InfowayClient();
```

### REST API 客户端

| 客户端                | 说明             |
| ------------------ | -------------- |
| `client.stock`     | 港股、美股、A股行情     |
| `client.crypto`    | 加密货币行情         |
| `client.japan`     | 日本股市行情         |
| `client.india`     | 印度股市行情         |
| `client.common`    | 跨市场通用行情        |
| `client.basic`     | 品种列表、交易日、交易时间  |
| `client.market`    | 市场温度、涨跌统计、全球指数 |
| `client.plate`     | 行业/概念板块分析      |
| `client.stockInfo` | 估值、评级、公司概览     |

#### 行情数据方法（stock / crypto / japan / india / common）

| 方法                                  | 说明       |
| ----------------------------------- | -------- |
| `getTrade(codes)`                   | 获取实时成交数据 |
| `getDepth(codes)`                   | 获取买卖盘口深度 |
| `getKline(codes, klineType, count)` | 获取K线数据   |

### WebSocket 实时推送

```typescript
import { InfowayWebSocket, Business } from "infoway-sdk";

const ws = new InfowayWebSocket({
  apiKey: "YOUR_API_KEY",
  business: Business.STOCK,
});

ws.onTrade = (msg) => {
  console.log("成交:", msg);
};

ws.onDepth = (msg) => {
  console.log("盘口:", msg);
};

ws.onKline = (msg) => {
  console.log("K线:", msg);
};

ws.onDisconnect = () => {
  console.log("连接断开，正在重连...");
};

ws.onReconnect = () => {
  console.log("已重连！");
};

await ws.subscribeTrade("AAPL.US,TSLA.US");
await ws.subscribeDepth("AAPL.US");
await ws.connect();
```

#### 加密货币 WebSocket

```typescript
const ws = new InfowayWebSocket({
  apiKey: "YOUR_API_KEY",
  business: Business.CRYPTO,
});

ws.onTrade = (msg) => console.log("加密货币成交:", msg);
await ws.subscribeTrade("BTCUSDT,ETHUSDT");
await ws.connect();
```

### K线类型

| 枚举值                      | 周期   |
| ------------------------ | ---- |
| `KlineType.MIN_1` (1)    | 1分钟  |
| `KlineType.MIN_5` (2)    | 5分钟  |
| `KlineType.MIN_15` (3)   | 15分钟 |
| `KlineType.MIN_30` (4)   | 30分钟 |
| `KlineType.HOUR_1` (5)   | 1小时  |
| `KlineType.HOUR_2` (6)   | 2小时  |
| `KlineType.HOUR_4` (7)   | 4小时  |
| `KlineType.DAY` (8)      | 日线   |
| `KlineType.WEEK` (9)     | 周线   |
| `KlineType.MONTH` (10)   | 月线   |
| `KlineType.QUARTER` (11) | 季线   |
| `KlineType.YEAR` (12)    | 年线   |

### 错误处理

```typescript
import { InfowayAPIError, InfowayAuthError, InfowayTimeoutError } from "infoway-sdk";

try {
  const data = await client.stock.getTrade("AAPL.US");
} catch (err) {
  if (err instanceof InfowayAuthError) {
    console.error("认证失败，请检查 API Key");
  } else if (err instanceof InfowayTimeoutError) {
    console.error("请求超时");
  } else if (err instanceof InfowayAPIError) {
    console.error(`API 错误 [${err.ret}]: ${err.msg}`);
  }
}
```

***