DEV Community

TikTool
TikTool

Posted on

Track TikTok LIVE Gifts in Real-Time with Python

#python #tiktok #websocket #tutorial

TikTok LIVE gifts are a massive economy — creators earn real money from virtual gifts. Here's how to track every gift on any live stream with Python, building a real-time diamond leaderboard.

I tested this on a live stream just now. Real output included below.

Install 

pip install tiktok-live-api
Enter fullscreen mode Exit fullscreen mode

Get your free API key at tik.tools (no credit card required).

The Code 

# gift-tracker.py — run with: python gift-tracker.py
from tiktok_live_api import TikTokLive

client = TikTokLive("USERNAME_HERE", api_key="YOUR_API_KEY")
gifts = {}
total_diamonds = 0

@client.on("connected")
def on_connected(event):
    print(f"✅ Connected to @{event['uniqueId']}")

@client.on("gift")
def on_gift(event):
    global total_diamonds
    user = event["user"]["uniqueId"]
    name = event["giftName"]
    diamonds = event.get("diamondCount", 0)
    count = event.get("repeatCount", 1)

    total_value = diamonds * count
    total_diamonds += total_value
    gifts[user] = gifts.get(user, 0) + total_value

    print(f"🎁 {user} sent {count}x {name} ({total_value} 💎)")
    print(f"   Stream total: {total_diamonds} 💎")

    # Show leaderboard
    top5 = sorted(gifts.items(), key=lambda x: -x[1])[:5]
    print("\n🏆 Leaderboard:")
    for i, (name, d) in enumerate(top5):
        print(f"  {i+1}. @{name} — {d} 💎")
    print()

@client.on("chat")
def on_chat(event):
    print(f"💬 {event['user']['uniqueId']}: {event['comment']}")

@client.on("roomUserSeq")
def on_viewers(event):
    print(f"👀 {event['viewerCount']} viewers watching")

client.run()
Enter fullscreen mode Exit fullscreen mode

Replace USERNAME_HERE with any TikTok username that's currently live, and YOUR_API_KEY with your free key.

Real Output

I ran this on a live stream. Actual terminal output:

✅ Connected to @gbnews
💬 damasiotis: Tha to skefto
💬 lydosfp: MPAOU MPAOU MONEY GUNS GALAXIES UNI KOLLHTA
💬 andrianniwww: Ετσι απλά το έστειλα μην χάσουμε το χ2
👀 18 viewers watching
🎁 andrianniwww sent 1x Hand Heart (100 💎)
   Stream total: 100 💎

🏆 Leaderboard:
  1. @andrianniwww — 100 💎
Enter fullscreen mode Exit fullscreen mode

Every gift shows instantly with diamond values, and the leaderboard updates live.

Available Events

Event Key Fields
chat event['user']['uniqueId'], event['comment']
gift event['user']['uniqueId'], event['giftName'], event['diamondCount']
like event['user']['uniqueId'], event['likeCount']
follow event['user']['uniqueId']
member event['user']['uniqueId'] (viewer joined)
roomUserSeq event['viewerCount']

Async Usage

For FastAPI, Django Channels, or any async framework:

import asyncio
from tiktok_live_api import TikTokLive

async def main():
    client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")

    @client.on("gift")
    async def on_gift(event):
        print(f"🎁 {event['user']['uniqueId']} sent {event['giftName']}")

    await client.connect()

asyncio.run(main())
Enter fullscreen mode Exit fullscreen mode

What Can You Build?

  • Discord webhooks — alert your server about big gifts
  • OBS overlays — display leaderboard on stream
  • Database logging — store gift history for analytics
  • AI live captions — real-time speech-to-text with translation (unique to this SDK)

Also Available

  • Node.js/TypeScript: npm install tiktok-live-api (npm)
  • Any language: Raw WebSocket: wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY
  • Full docs: tik.tools/docs

Free tier: 50 requests/day — enough to build and test.

Top comments (0)