Developer API
TikTok LIVE API in Node.js
@toktikhq/sdk-js is the official JavaScript and TypeScript client for the Toktik Developer API: typed REST methods and a realtime stream with automatic reconnects. This guide goes from npm install to a streaming gift counter.
Updated
Package: @toktikhq/sdk-js 0.4.1 on npm
1. Install
npm i @toktikhq/sdk-js2. Authenticate
Create an API key (see the quickstart) and keep it out of source control — read it from an environment variable. Give the key only the scopes it needs, for example rank:read for rankings.
import { TokTikClient } from "@toktikhq/sdk-js";
const client = new TokTikClient({ apiKey: process.env.TOKTIK_API_KEY! });3. Fetch rankings
The official ranking boards (hourly, daily, Popular LIVE, gaming, LIVE Shopping and the A1–D5 League) are one call. On the free tier creator identities below the open top rows are masked; rank, score and movement always show.
const board = await client.rankings.official({ board: "hourly", region: "VN" });
for (const row of board.data.board.entries.slice(0, 3)) console.log(row.rank, row.nickname, row.score);
const perf = await client.live.creatorPerformance("some.creator", { limit: 20 });4. Stream gifts in realtime
Subscribe to the creators you follow and receive decoded events as they happen. The client mints and refreshes the handshake token and resumes your subscriptions after a reconnect. Realtime is metered per room-minute. A free key can hold 1 connection and 100 room-minutes a month; paid tiers raise both. See the realtime reference for every frame and event type.
import { TokTikClient } from "@toktikhq/sdk-js";
const client = new TokTikClient({ apiKey: process.env.TOKTIK_API_KEY! });
const stream = await client.live.stream(["@creator_handle"], {
onStatus: (s) => console.log("status", s.creatorId, s.status), // queued → active
onEvent: (frame) => {
if (frame.event === "gift") {
const g = frame.data.decoded;
if (g.isCompleted) console.log(g.gift?.giftName, (g.gift?.diamondCount ?? 0) * g.repeatCount);
}
},
onError: (e) => console.error(e),
onReconnect: (attempt) => console.warn("reconnected", attempt)
});
// later: await stream.close();5. Handle errors and limits
One typed error covers every failure. 402 means out of credits, 403 a missing scope, and 429 or 5xx are safe to retry with back-off.
import { TokTikClient, TokTikApiError } from "@toktikhq/sdk-js";
try {
await client.creators.get("someone");
} catch (err) {
if (err instanceof TokTikApiError) {
if (err.isPaymentRequired) {/* 402 — top up credits */}
else if (err.status === 403) {/* missing scope */}
else if (err.retryable) {/* 429 / 5xx — back off and retry */}
}
}A complete script
Put it together: set TOKTIK_API_KEY, run it, and you get the top of the Vietnam hourly board.
import { TokTikApiError, TokTikClient } from "@toktikhq/sdk-js";
const apiKey = process.env.TOKTIK_API_KEY;
if (!apiKey) throw new Error("set TOKTIK_API_KEY");
const client = new TokTikClient({ apiKey });
try {
const board = await client.rankings.official({ board: "hourly", region: "VN" });
const rows = board.data.board.entries;
console.log(`${rows.length} creators on the VN hourly board`);
for (const row of rows.slice(0, 3)) console.log(row.rank, row.nickname, row.score);
} catch (err) {
if (err instanceof TokTikApiError && err.isPaymentRequired) {
console.error("out of credits (402): top up or wait for the cycle");
process.exit(1);
}
throw err;
}Frequently asked questions
How do I get TikTok LIVE data in Node.js?
Install @toktikhq/sdk-js (npm i @toktikhq/sdk-js), create a Toktik API key, and call the client: rankings, gifters, agencies, creator performance and a realtime stream are all methods on one client. Each response includes the provenance (when and from what source the data was observed).
Does the Node.js SDK work with TypeScript and in the browser?
It ships its own TypeScript types and uses the platform fetch and WebSocket. Keep the API key on the server: a key embedded in browser code is visible to every visitor, so call Toktik from your backend and pass the result on.
How are errors and rate limits reported?
As HTTP status codes in a typed error: 402 means out of credits, 403 a missing scope, 429 a rate limit (with Retry-After) and 5xx a server fault. The error object tells you whether a retry is safe, so one handler covers every call.
Is this the official TikTok API?
No. It is Toktik's own API for the public TikTok LIVE data Toktik observes. Toktik is independent and not affiliated with TikTok.
TikTok LIVE API overviewPython guideAPI reference
Toktik is independent and not affiliated with TikTok.