> 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/en-docs/sdk-and-tools/nodejs-sdk.md).

# Node.js SDK

### Overview

Official Node.js/TypeScript SDK for the Infoway real-time financial data API, with full TypeScript type definitions and dual ESM/CJS output.

| Item    | Details                                                                             |
| ------- | ----------------------------------------------------------------------------------- |
| npm     | [`infoway-sdk`](https://www.npmjs.com/package/infoway-sdk)                          |
| Node.js | 18+                                                                                 |
| License | MIT                                                                                 |
| GitHub  | [infoway-api/infoway-sdk-nodejs](https://github.com/infoway-api/infoway-sdk-nodejs) |

### Installation

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

### Quick Start

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

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

// Stock trade data
const trades = await client.stock.getTrade("AAPL.US");

// Multiple symbols
const multiTrades = await client.stock.getTrade("AAPL.US,TSLA.US,GOOGL.US");

// Order book depth
const depth = await client.stock.getDepth("AAPL.US");

// K-line data
const klines = await client.stock.getKline("AAPL.US", KlineType.DAY, 100);

// Crypto data
const btc = await client.crypto.getTrade("BTCUSDT");

// Market temperature
const temp = await client.market.getTemperature("HK,US");

// Stock fundamentals
const valuation = await client.stockInfo.getValuation("AAPL.US");

// Plate / sector data
const industries = await client.plate.getIndustry("HK");
```

### Configuration

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

```typescript
// Reads INFOWAY_API_KEY from environment automatically
const client = new InfowayClient();
```

### REST API Clients

| Client             | Description                      |
| ------------------ | -------------------------------- |
| `client.stock`     | HK, US, CN stock market data     |
| `client.crypto`    | Cryptocurrency data              |
| `client.japan`     | Japan stock market data          |
| `client.india`     | India stock market data          |
| `client.common`    | Common market data               |
| `client.basic`     | Symbols, trading days, hours     |
| `client.market`    | Temperature, breadth, indexes    |
| `client.plate`     | Industry / concept sectors       |
| `client.stockInfo` | Valuation, ratings, company info |

#### Market Data Methods (stock / crypto / japan / india / common)

| Method                              | Description              |
| ----------------------------------- | ------------------------ |
| `getTrade(codes)`                   | Get real-time trade data |
| `getDepth(codes)`                   | Get order book depth     |
| `getKline(codes, klineType, count)` | Get K-line data          |

### WebSocket Streaming

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

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

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

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

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

ws.onDisconnect = () => {
  console.log("Disconnected, reconnecting...");
};

ws.onReconnect = () => {
  console.log("Reconnected!");
};

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

#### Crypto WebSocket

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

ws.onTrade = (msg) => console.log("Crypto trade:", msg);
await ws.subscribeTrade("BTCUSDT,ETHUSDT");
await ws.connect();
```

### K-line Types

| Enum                     | Interval   |
| ------------------------ | ---------- |
| `KlineType.MIN_1` (1)    | 1 minute   |
| `KlineType.MIN_5` (2)    | 5 minutes  |
| `KlineType.MIN_15` (3)   | 15 minutes |
| `KlineType.MIN_30` (4)   | 30 minutes |
| `KlineType.HOUR_1` (5)   | 1 hour     |
| `KlineType.HOUR_2` (6)   | 2 hours    |
| `KlineType.HOUR_4` (7)   | 4 hours    |
| `KlineType.DAY` (8)      | 1 day      |
| `KlineType.WEEK` (9)     | 1 week     |
| `KlineType.MONTH` (10)   | 1 month    |
| `KlineType.QUARTER` (11) | 1 quarter  |
| `KlineType.YEAR` (12)    | 1 year     |

### Error Handling

```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("Authentication failed. Check your API key.");
  } else if (err instanceof InfowayTimeoutError) {
    console.error("Request timed out.");
  } else if (err instanceof InfowayAPIError) {
    console.error(`API error [${err.ret}]: ${err.msg}`);
  }
}
```

***