tiktok-live-api

Agency rank feeds in Discord: gaming ranks, creator ranks and 99+ movers across all 30 regions, copy-paste usernames for backstage. Run /ranks to start (Global Agency).

TikTok LIVE API for Node.js

tiktok-live-api is the most complete, production-managed TikTok LIVE API for Node.js and TypeScript. Connect to any TikTok LIVE stream over a single WebSocket and receive real-time chat messages, gifts, likes, follows, viewer counts, shares and battle events - plus AI live captions with 60+ language translation, an Unreal Engine plugin, and SDKs in multiple languages. Managed signing works out of the box: no third-party sign server, no keys to configure. Powered by the TikTool managed API.

Docs and dashboard: tik.tools  |  Python SDK: tik.tools/guides/python-tiktok-live  |  WebSocket API: tik.tools/websocket

This package is not affiliated with or endorsed by TikTok. It connects to the TikTool Live managed API service - 99.9% uptime, no reverse engineering, no maintenance required. Also available for Python and any language via WebSocket.

Why tik.tools

The premium managed alternative for TikTok LIVE data. What you get out of the box:

• Managed signing infrastructure. Signing runs on our servers and works immediately - no third-party sign server to run, no separate key to configure.
• AI live captions and translation. Real-time speech-to-text with 60+ language translation and speaker labels, available on no other TikTok LIVE library.
• Unreal Engine plugin. Drive avatars, overlays and gameplay directly from live chat, gifts and battles.
• Agency and leaderboard intelligence. Gifter leaderboards, gaming and creator ranks across regions, and eligible-creator discovery.
• Multi-language SDKs. First-class Node.js and Python clients plus a plain WebSocket API for any language.
• Free Sandbox tier. Start building for free, upgrade only when you need higher limits or unmasked data.

Install

npm install tiktok-live-api

# or with yarn / pnpm / bun
yarn add tiktok-live-api
pnpm add tiktok-live-api
bun add tiktok-live-api

Quick Start

import { TikTokLive } from 'tiktok-live-api';

const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });

client.on('chat', (event) => {
  console.log(`${event.user.uniqueId}: ${event.comment}`);
});

client.on('gift', (event) => {
  console.log(`${event.user.uniqueId} sent ${event.giftName} (${event.diamondCount} 💎)`);
});

client.on('like', (event) => {
  console.log(`${event.user.uniqueId} liked (total: ${event.totalLikes})`);
});

client.on('follow', (event) => {
  console.log(`${event.user.uniqueId} followed!`);
});

client.on('roomUserSeq', (event) => {
  console.log(`${event.viewerCount} viewers watching`);
});

client.connect();

That's it. No complex setup, no protobuf, no reverse engineering, no breakages when TikTok updates.

Try It Now - Live Demo

Copy-paste this into a file and run it. Connects to a live TikTok stream and prints every event in real time. Works on the free Community tier - 2 hours per WebSocket connection.

Save as demo.mjs and run with node demo.mjs:

// demo.mjs - TikTok LIVE in real time
// npm install tiktok-live-api
import { TikTokLive } from 'tiktok-live-api';

const API_KEY       = 'YOUR_API_KEY';        // Get free key → https://tik.tools
const LIVE_USERNAME = 'tv_asahi_news';       // Any live TikTok username

const client = new TikTokLive(LIVE_USERNAME, { apiKey: API_KEY });
let events = 0;

client.on('chat',        e => { events++; console.log(`💬 ${e.user.uniqueId}: ${e.comment}`); });
client.on('gift',        e => { events++; console.log(`🎁 ${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount}💎)`); });
client.on('like',        e => { events++; console.log(`❤️  ${e.user.uniqueId} liked × ${e.likeCount}`); });
client.on('member',      e => { events++; console.log(`👋 ${e.user.uniqueId} joined`); });
client.on('follow',      e => { events++; console.log(`➕ ${e.user.uniqueId} followed`); });
client.on('roomUserSeq', e => { events++; console.log(`👀 Viewers: ${e.viewerCount}`); });

client.on('connected',    () => console.log(`\n✅ Connected to @${LIVE_USERNAME} - streaming events...\n`));
client.on('disconnected', () => console.log(`\n📊 Disconnected. Received ${events} events.\n`));

client.connect();
// Press Ctrl+C to stop. Community tier caps each WebSocket at 2 hours.

// ws-demo.mjs - Pure WebSocket, zero SDK
// npm install ws
import WebSocket from 'ws';

const API_KEY       = 'YOUR_API_KEY';
const LIVE_USERNAME = 'tv_asahi_news';

const ws = new WebSocket(`wss://api.tik.tools?uniqueId=${LIVE_USERNAME}&apiKey=${API_KEY}`);
let events = 0;

ws.on('open', () => console.log(`\n✅ Connected to @${LIVE_USERNAME} - streaming events...\n`));
ws.on('message', (raw) => {
  const msg = JSON.parse(raw);
  events++;
  const d = msg.data || {};
  const user = d.user?.uniqueId || '';
  switch (msg.event) {
    case 'chat':        console.log(`💬 ${user}: ${d.comment}`); break;
    case 'gift':        console.log(`🎁 ${user} sent ${d.giftName} (${d.diamondCount}💎)`); break;
    case 'like':        console.log(`❤️  ${user} liked × ${d.likeCount}`); break;
    case 'member':      console.log(`👋 ${user} joined`); break;
    case 'roomUserSeq': console.log(`👀 Viewers: ${d.viewerCount}`); break;
    case 'roomInfo':    console.log(`📡 Room: ${msg.roomId}`); break;
    default:            console.log(`📦 ${msg.event}`); break;
  }
});
ws.on('close', () => console.log(`\n📊 Disconnected. Received ${events} events.\n`));
// Press Ctrl+C to stop. Community tier caps each WebSocket at 2 hours.

JavaScript (CommonJS)

const { TikTokLive } = require('tiktok-live-api');

const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
client.on('chat', (e) => console.log(`${e.user.uniqueId}: ${e.comment}`));
client.connect();

Get a Free API Key

1. Go to tik.tools
2. Sign up (no credit card required)
3. Copy your API key

The free Community tier gives you 5,000 requests/day, 3 concurrent WebSocket streams (60 new connects/hour, 2 hours per connection). Forever free.

Environment Variable

Instead of passing apiKey directly, you can set it as an environment variable:

# Linux / macOS
export TIKTOOL_API_KEY=your_api_key_here

# Windows (CMD)
set TIKTOOL_API_KEY=your_api_key_here

# Windows (PowerShell)
$env:TIKTOOL_API_KEY="your_api_key_here"

import { TikTokLive } from 'tiktok-live-api';

// Automatically reads TIKTOOL_API_KEY from environment
const client = new TikTokLive('streamer_username');
client.on('chat', (e) => console.log(e.comment));
client.connect();

REST API - leaderboards, recruiting, profiles, gifts

The WebSocket client streams live events. For everything else - leaderboards, gaming ranks, recruiting, live status, gift catalogs, profiles - use the TikTool REST client. One method per endpoint, fully promise-based.

import { TikTool } from 'tiktok-live-api';

const api = new TikTool({ apiKey: 'YOUR_KEY' });

// Live status (single + bulk)
await api.liveStatus('charlidamelio');
await api.bulkLiveCheck(['user1', 'user2', 'user3']);

// Leaderboards + rankings
await api.leaderboard({ region: 'US+' });
await api.ranklistGaming('US+');
await api.regionMovers('US+');           // entered top today, below cutoff now

// Recruiting (Global Agency) - find eligible creators
await api.eligibleCreators({ region: 'US+', limit: 50, min_score: 1000 });

// Profiles + gifts
await api.profileInfo('khaby.lame');
await api.userProfile('khaby.lame');
await api.giftsByCountry('US');

Tier gating is enforced server-side: a call above your tier throws a TikToolError with status === 403. Any endpoint not yet wrapped is reachable via api.request('/webcast/...', { query }).

import { TikTool, TikToolError } from 'tiktok-live-api';
try {
  await api.eligibleCreators({ region: 'US+' });
} catch (e) {
  if (e instanceof TikToolError && e.status === 403) {
    console.log('Upgrade required:', e.message);
  }
}

Method groups: signing/connection, live status, rankings/leaderboards, gifts, user/profile, content/feed, live analytics, moderation, CAPTCHA solver, captions. See the full endpoint + tier matrix.

Events (54 v3 event types)

Every event is dispatched by name. client.on('chat', e => ...) is fully typed end-to-end. Each event payload extends BaseEvent (type, timestamp, msgId, optional protoVersion: 1 | 2 | 3).

Core live events

PK / battle events

Native captions (v3)

Creator-side events

Moderation / safety

Gift catalog + ecommerce

Engagement + AI

Catch-all

• event - Fires for every decoded event (dump-to-queue pattern).
• unknown - Fires when TikTok ships a method we don't yet model (forward-compat hook).

All events are fully typed with TypeScript interfaces. Your IDE will show autocompletion for every field. See full per-event JSON examples + field tables.

Battle / PK example

import { TikTokLive } from 'tiktok-live-api';

const client = new TikTokLive({ uniqueId: 'creator_username', apiKey: 'tk_...' });

client.on('battle', e => console.log('PK', e.status, e.battleId, 'duration=', e.battleDuration));

client.on('battleArmies', e => {
  console.log('Countdown:', e.secsRemaining, 's');
  for (const host of e.hosts ?? []) {
    console.log(`@${host.hostUserId} team total=${host.teamTotalScore}`);
    const mvp = host.contributors[0];
    if (mvp) console.log(`  MVP @${mvp.nickname} score=${mvp.score}`);
  }
});

client.on('battleItemCard', e => {
  if (e.multiplier > 0) console.log(`x${e.multiplier} booster from @${e.senderUniqueId}`);
  else console.log(`Effect ${e.effect} from @${e.senderUniqueId} (${e.durationSec}s)`);
});

await client.connect();

Live Captions (Speech-to-Text)

Transcribe and translate any TikTok LIVE stream in real-time. This feature is unique to TikTool Live - no other TikTok library offers it.

import { TikTokCaptions } from 'tiktok-live-api';

const captions = new TikTokCaptions('streamer_username', {
  apiKey: 'YOUR_API_KEY',
  translate: 'en',       // translate to English
  diarization: true,     // identify who is speaking
});

captions.on('caption', (event) => {
  const speaker = event.speaker ? `[${event.speaker}] ` : '';
  console.log(`${speaker}${event.text}${event.isFinal ? ' ✓' : '...'}`);
});

captions.on('translation', (event) => {
  console.log(`  → ${event.text}`);
});

captions.on('credits', (event) => {
  console.log(`${event.remaining}/${event.total} minutes remaining`);
});

captions.connect();

Caption Events

Chat Bot Example

import { TikTokLive } from 'tiktok-live-api';

const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
const giftLeaderboard = new Map<string, number>();
let messageCount = 0;

client.on('chat', (event) => {
  messageCount++;
  const msg = event.comment.toLowerCase().trim();
  const user = event.user.uniqueId;

  if (msg === '!hello') {
    console.log(`>> BOT: Welcome ${user}! 👋`);
  } else if (msg === '!stats') {
    console.log(`>> BOT: ${messageCount} messages, ${giftLeaderboard.size} gifters`);
  } else if (msg === '!top') {
    const top = [...giftLeaderboard.entries()]
      .sort((a, b) => b[1] - a[1])
      .slice(0, 5);
    top.forEach(([name, diamonds], i) => {
      console.log(`  ${i + 1}. ${name} - ${diamonds} 💎`);
    });
  }
});

client.on('gift', (event) => {
  const user = event.user.uniqueId;
  const diamonds = event.diamondCount || 0;
  giftLeaderboard.set(user, (giftLeaderboard.get(user) || 0) + diamonds);
});

client.connect();

TypeScript

This package ships with full TypeScript support. All events are typed:

import { TikTokLive, ChatEvent, GiftEvent } from 'tiktok-live-api';

const client = new TikTokLive('streamer', { apiKey: 'KEY' });

// Full autocompletion - your IDE knows the type of `event`
client.on('chat', (event: ChatEvent) => {
  console.log(event.user.uniqueId);  // ✓ typed
  console.log(event.comment);        // ✓ typed
});

client.on('gift', (event: GiftEvent) => {
  console.log(event.giftName);       // ✓ typed
  console.log(event.diamondCount);   // ✓ typed
});

API Reference

new TikTokLive(uniqueId, options?)

Methods:

• client.on(event, handler) - Register event handler
• client.off(event, handler) - Remove event handler
• client.connect() - Connect to stream (returns Promise)
• client.disconnect() - Disconnect from stream
• client.connected - Whether currently connected
• client.eventCount - Total events received

new TikTokCaptions(uniqueId, options?)

Methods:

• captions.on(event, handler) - Register event handler
• captions.off(event, handler) - Remove event handler
• captions.connect() - Start receiving captions (returns Promise)
• captions.disconnect() - Stop receiving captions
• captions.connected - Whether currently connected

Why tiktok-live-api?

Pricing

Tier is enforced server-side by your API key. Snapshot below; the full feature matrix lives at tik.tools/pricing.

• Community ($0 forever): 3 concurrent WS, 2h per session, masked leaderboards, read-only gift catalog sample. Designed for devs building apps - upgrade when you need real usernames or more than ~5 connections (TikTok's per-IP limit). No datacenter proxies; calls come from your own IP.
• Basic ($7/wk - $19/mo): 60 req/min, 20 concurrent WS, 8h per WS, datacenter proxies, masked leaderboards, 12h/wk - 60h/mo of bundled AI Live Captions.
• Pro ($15/wk - $49/mo): 300 req/min, 50 concurrent WS, 12h per WS, unmasked leaderboards, Feed Discovery, regional leaderboard signed URLs, 30h/wk - 140h/mo of bundled AI Live Captions.
• Ultra ($45/wk - $149/mo): 1,000 req/min, 250 concurrent WS, 24h per WS, Gift Catalog API (full TikTok gift catalog continuously re-synced), League Rankings unmasked, CSV exports, 99.5% uptime SLA, 60h/wk - 260h/mo of bundled AI Live Captions.
• Global Agency ($119/wk - $399/mo): Everything in Ultra plus Live Gifter Firehose WS (region / league / global filters + min-diamond threshold), VIP Telegram alerts, VIP Web Vault (unmasked historical visual access), gifter intel unmasked, 500 concurrent WS, 120h/wk - 500h/mo of bundled AI Live Captions.

Standalone AI Live Captions plans (no API key needed) on tik.tools/captions: Casual ($7/wk - $29/mo for 12h/wk - 60h/mo), Pro ($15/wk - $59/mo for 30h/wk - 140h/mo), Extreme ($29/wk - $99/mo for 60h/wk - 260h/mo). Auto-renew + early-renewal on exhaust so captions never drop mid-stream.

Live Gifter Firehose - Global Agency

Real-time gift event stream from our Dragonfly fan-out. Filter by region, league, or globally; cap by minimum diamond threshold. Mid-stream filter updates supported via update_filter frame, no reconnect needed.

const ws = new WebSocket(
  `wss://api.tik.tools/firehose/gifters?apiKey=${KEY}&mode=region&region=US%2B&min_diamonds=1000`
)
ws.on('message', (raw) => {
  const evt = JSON.parse(raw)
  // evt: { type:'gifter_alert', ts, gifter:{username,displayName,isAnonymous},
  //        creator:{uniqueId}, gift:{name,totalDiamonds}, region }
})
// Update filter without reconnect
ws.send(JSON.stringify({ type: 'update_filter', mode: 'global', min_diamonds: 5000 }))

Modes: global (all regions), region (single region code), league (region + league class, e.g. B2).

Also Available

• Python: pip install tiktok-live-api
• Any language: Connect via WebSocket: wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY
• Unreal Engine: Native C++/Blueprint plugin

Links

• Website: tik.tools
• Documentation: tik.tools/docs
• Python SDK: pypi.org/project/tiktok-live-api
• GitHub: github.com/tiktool/tiktok-live-api

License

MIT