> ## Documentation Index
> Fetch the complete documentation index at: https://tiktools.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Official TikTool Node.js SDK - connect to any TikTok Live stream with a simple, event-driven API.

## Installation

```bash theme={null}
npm install @tiktool/live
```

## Quick Start

```javascript theme={null}
import { TikTokLive } from '@tiktool/live';

const client = new TikTokLive({
  apiKey: process.env.TIKTOOL_API_KEY,
  uniqueId: 'streamer_username',
});

client.on('connected', () => console.log('Connected!'));
client.on('chat', (event) => console.log(`${event.user.uniqueId}: ${event.comment}`));
client.on('gift', (event) => console.log(`${event.user.uniqueId} sent ${event.giftName}`));
client.on('like', (event) => console.log(`${event.user.uniqueId} liked × ${event.likeCount}`));

await client.connect();
```

## Configuration

| Option                     | Type    | Default | Description                                     |
| -------------------------- | ------- | ------- | ----------------------------------------------- |
| `apiKey`                   | string  | -       | Your TikTool API key                            |
| `uniqueId`                 | string  | -       | TikTok username to connect to                   |
| `enableExtendedGiftInfo`   | boolean | `false` | Fetch full gift details (image, diamond values) |
| `requestPollingIntervalMs` | number  | `1000`  | Polling interval for HTTP mode                  |

## Events

All events from the [WebSocket Events](/websocket/events) reference are available:

```javascript theme={null}
client.on('chat', (event) => { /* chat message */ });
client.on('gift', (event) => { /* virtual gift */ });
client.on('like', (event) => { /* likes */ });
client.on('member', (event) => { /* viewer joined */ });
client.on('follow', (event) => { /* new follower */ });
client.on('share', (event) => { /* stream shared */ });
client.on('roomUserSeq', (event) => { /* viewer count update */ });
client.on('subscribe', (event) => { /* new subscriber */ });
client.on('battle', (event) => { /* PK on/off */ });
client.on('battleArmies', (event) => { /* PK score + MVP breakdown */ });
client.on('battleItemCard', (event) => { /* x2/x3 boosters, gloves, mist, ... */ });
client.on('emote', (event) => { /* animated emote */ });
client.on('envelope', (event) => { /* treasure box */ });
client.on('questionNew', (event) => { /* Q&A question */ });
client.on('roomPin', (event) => { /* starred / pinned message */ });
```

### PK Battles - MVP + Boosters

```javascript theme={null}
client.on('battleArmies', (e) => {
  console.log(`⏱ ${e.secsRemaining}s left`);
  for (const host of e.hosts ?? []) {
    const mvp = host.contributors[0]; // sorted MVP first
    console.log(`${host.hostUserId}: ${host.teamTotalScore} (MVP: ${mvp?.nickname} ${mvp?.score})`);
  }
});

client.on('battleItemCard', (e) => {
  const tag = e.multiplier > 0 ? `x${e.multiplier} BOOSTER` : e.effect.toUpperCase();
  console.log(`💥 ${e.senderNickname} → ${tag}`);
  // e.iconUrl / e.accentColor → drop-in OBS overlay
});
```

## Source Code

<Card title="GitHub Repository" icon="github" href="https://github.com/tiktool/tiktok-live-api">
  MIT-licensed. Full source code available.
</Card>