TikTok LIVE Agency SDK

What it does for agencies

tiktok-live-agency wraps the tik.tools API in a typed client built for TikTok LIVE agencies (Creator Networks, TCN, MCN). The same package name is on npm and PyPI, and both clients share one method list.

• Find creators to recruit. Ranked creators per region who are candidates to join an agency, new arrivals in the recruit pool, and creators dropping out of the leagues.
• Roster live status and diamonds. Check which of your creators are live right now, and read diamonds per creator and per roster from gifts captured during their streams.
• Webhooks. Signed go-live and stream-end alerts to your server, with a verifier for Node, Edge, Workers and Python.
• Custom dashboards. Plain JSON with the API's own field names, so the data drops straight into a Next.js page, a notebook or a spreadsheet export.

Install

JavaScript and TypeScript

npm install tiktok-live-agency

Python

pip install tiktok-live-agency

# optional, for the real-time big gifts stream
pip install "tiktok-live-agency[realtime]"

Set your key in the TIKTOOLS_API_KEY environment variable on the server. Never ship it to a browser: the TypeScript client refuses to start in a browser page. Keys are on the pricing page.

Examples

Which of my creators are live (TypeScript)

import { AgencyClient } from 'tiktok-live-agency'

const tt = new AgencyClient() // reads TIKTOOLS_API_KEY

const { live, offline, unknown } = await tt.whoIsLive(['creator_one', 'creator_two', 'creator_three'])
console.log(live.map((r) => r.unique_id))

Verify a go-live webhook in a Next.js Route Handler (TypeScript)

// app/api/webhooks/tiktools/route.ts
import { verifyWebhook } from 'tiktok-live-agency/webhooks'

export async function POST(req: Request) {
  const raw = await req.text() // raw body, verify before parsing
  try {
    const event = await verifyWebhook(raw, req.headers, process.env.TIKTOOLS_WEBHOOK_SECRET!)
    console.log(event.event, event.creator.unique_id)
  } catch {
    return new Response('bad signature', { status: 400 })
  }
  return new Response('ok')
}

Creators to recruit and roster diamonds (Python)

from tiktok_live_agency import AgencyClient, is_free_to_join

tt = AgencyClient()  # reads TIKTOOLS_API_KEY

rows = list(tt.iter_creators_to_recruit("UK", max_pages=5))
free = [r for r in rows if is_free_to_join(r)]

roster = tt.list_rosters()["lists"][0]
week = tt.roster_diamonds(roster["id"], days=7)
print(len(free), week["totalDiamonds"])

A call your plan does not include throws PlanRequiredError with the required plan and an upgrade link, so a dashboard can show an upgrade card instead of crashing. Webhook payloads and signatures are documented in the API reference.

Method groups

Python uses the same names in snake_case, for example who_is_live and find_creators_to_recruit. Every method with its plan is listed in each package README.

For AI assistants

A machine-readable summary of every method lives at tik.tools/sdk/agency/llms.txt. Point Cursor, Claude, ChatGPT or any AI builder at it, and name the package tiktok-live-agency, so generated code uses real data from the API.

Source and packages

• TypeScript: github.com/tiktool/tiktok-live-agency and npm
• Python: github.com/tiktool/tiktok-live-agency-python and PyPI
• License: MIT

Unofficial, not affiliated with TikTok or ByteDance. tiktok-live-agency is an independent SDK for the tik.tools API. TikTok is a trademark of its respective owner, used here only to describe compatibility.