Leaderboard & League API

[
  {
    "rank": 1,
    "uniqueId": "top_creator",
    "nickname": "Top Creator",
    "score": 284500,
    "isLive": true,
    "roomId": "7384920175638291456"
  },
  {
    "rank": 2,
    "uniqueId": "second_place",
    "nickname": "Second Place",
    "score": 198200,
    "isLive": false,
    "roomId": null
  }
]

// Node.js - fetch Balkans leaderboard
const response = await fetch('https://tik.tools/api/leaderboards/country/balkans', {
  headers: {
    'x-api-key': 'YOUR_ULTRA_API_KEY',
  }
})

const entries = await response.json()

for (const entry of entries) {
  console.log(`#${entry.rank} @${entry.uniqueId} - ${entry.score} diamonds${entry.isLive ? ' [LIVE]' : ''}`)
}

import httpx

# Python - fetch Balkans leaderboard
response = httpx.get(
    'https://tik.tools/api/leaderboards/country/balkans',
    headers={'x-api-key': 'YOUR_ULTRA_API_KEY'}
)

entries = response.json()

for entry in entries:
    live_tag = ' [LIVE]' if entry['isLive'] else ''
    print(f"#{entry['rank']} @{entry['uniqueId']} - {entry['score']} diamonds{live_tag}")

# cURL - fetch Balkans leaderboard (public)
curl -s \
  "https://tik.tools/api/leaderboards/country/balkans" \
  | jq '.[] | "#\(.rank) @\(.uniqueId) - \(.score) diamonds"'

// Browser JavaScript - call from a logged-in tik.tools session
// The session cookie is sent automatically
const response = await fetch('/api/leaderboards/country/balkans')
const entries = await response.json()

const live = entries.filter(e => e.isLive)
console.log(`${live.length} creators currently live in Balkans`)

// Sort by score descending (already sorted, just displaying)
entries.forEach(e => {
  console.log(`#${e.rank} ${e.nickname}: ${e.score.toLocaleString()} diamonds`)
})

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type LeaderboardEntry struct {
	Rank     int    `json:"rank"`
	UniqueId string `json:"uniqueId"`
	Nickname string `json:"nickname"`
	Score    int    `json:"score"`
	IsLive   bool   `json:"isLive"`
	RoomId   string `json:"roomId"`
}

func main() {
	req, _ := http.NewRequest("GET",
		"https://tik.tools/api/leaderboards/country/balkans", nil)
	req.Header.Set("x-api-key", "YOUR_ULTRA_API_KEY")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var entries []LeaderboardEntry
	json.NewDecoder(resp.Body).Decode(&entries)

	for _, e := range entries {
		liveTag := ""
		if e.IsLive {
			liveTag = " [LIVE]"
		}
		fmt.Printf("#%d @%s - %d diamonds%s\n", e.Rank, e.UniqueId, e.Score, liveTag)
	}
}

<?php
// PHP - fetch Balkans leaderboard (public endpoint, no auth needed)
$json = file_get_contents(
    'https://tik.tools/api/leaderboards/country/balkans'
);

$entries = json_decode($json, true);

foreach ($entries as $entry) {
    $live = $entry['isLive'] ? ' [LIVE]' : '';
    echo "#{$entry['rank']} @{$entry['uniqueId']} - {$entry['score']} diamonds{$live}\n";
}

[
  { "classType": 2000, "classLabel": "A1", "count": 12, "updatedAt": "2026-05-11T14:30:00.000Z" },
  { "classType": 1900, "classLabel": "A2", "count": 28, "updatedAt": "2026-05-11T14:30:00.000Z" },
  { "classType": 1100, "classLabel": "B5", "count": 55, "updatedAt": "2026-05-11T14:30:00.000Z" },
  { "classType": 1000, "classLabel": "C1", "count": 83, "updatedAt": "2026-05-11T14:30:00.000Z" }
]

// Node.js - list leagues for Balkans (BK)
const response = await fetch('https://tik.tools/api/leaderboards/leagues/BK', {
  headers: { 'x-api-key': 'YOUR_ULTRA_API_KEY' }
})

const leagues = await response.json()

for (const league of leagues) {
  console.log(`${league.classLabel} (type ${league.classType}): ${league.count} creators`)
}

import httpx

# Python - list leagues for Balkans (BK)
response = httpx.get(
    'https://tik.tools/api/leaderboards/leagues/BK',
    headers={'x-api-key': 'YOUR_ULTRA_API_KEY'}
)

leagues = response.json()

for league in leagues:
    print(f"{league['classLabel']} (type {league['classType']}): {league['count']} creators")

# cURL - list leagues for Balkans (BK)
curl -s \
  -H "x-api-key: YOUR_ULTRA_API_KEY" \
  "https://tik.tools/api/leaderboards/leagues/BK" \
  | jq '.[] | "\(.classLabel): \(.count) creators"'

// Browser JavaScript - list leagues (from logged-in session)
const response = await fetch('/api/leaderboards/leagues/BK')
const leagues = await response.json()

leagues.forEach(l => {
  console.log(`${l.classLabel}: ${l.count} creators (updated ${new Date(l.updatedAt).toLocaleTimeString()})`)
})

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type LeagueInfo struct {
	ClassType  int    `json:"classType"`
	ClassLabel string `json:"classLabel"`
	Count      int    `json:"count"`
	UpdatedAt  string `json:"updatedAt"`
}

func main() {
	req, _ := http.NewRequest("GET",
		"https://tik.tools/api/leaderboards/leagues/BK", nil)
	req.Header.Set("x-api-key", "YOUR_ULTRA_API_KEY")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var leagues []LeagueInfo
	json.NewDecoder(resp.Body).Decode(&leagues)

	for _, l := range leagues {
		fmt.Printf("%s (type %d): %d creators\n", l.ClassLabel, l.ClassType, l.Count)
	}
}

<?php
// PHP - list leagues for Balkans (BK)
$context = stream_context_create([
    'http' => ['header' => "x-api-key: YOUR_ULTRA_API_KEY\r\n"]
]);

$json = file_get_contents(
    'https://tik.tools/api/leaderboards/leagues/BK',
    false, $context
);

$leagues = json_decode($json, true);

foreach ($leagues as $league) {
    echo "{$league['classLabel']} (type {$league['classType']}): {$league['count']} creators\n";
}

{
  "hasFullAccess": true,
  "maskedCount": 0,
  "totalCount": 12,
  "entries": [
    {
      "rank": 1,
      "userId": "6841523190294479361",
      "uniqueId": "league_leader",
      "nickname": "League Leader",
      "score": 1840000,
      "isLive": true
    },
    {
      "rank": 2,
      "userId": "6712309845712006148",
      "uniqueId": "second_in_a1",
      "nickname": "Second In A1",
      "score": 1620000,
      "isLive": false
    }
  ]
}

// Node.js - fetch A1 league entries for Balkans
const response = await fetch('https://tik.tools/api/leaderboards/league/BK/2000', {
  headers: { 'x-api-key': 'YOUR_ULTRA_API_KEY' }
})

const data = await response.json()

if (!data.hasFullAccess) {
  console.warn(`Teaser mode: ${data.maskedCount} entries hidden. Upgrade to Ultra for full access.`)
}

console.log(`A1 Balkans - ${data.totalCount} creators total`)

for (const entry of data.entries) {
  const liveTag = entry.isLive ? ' [LIVE]' : ''
  console.log(`#${entry.rank} @${entry.uniqueId} - ${entry.score.toLocaleString()} diamonds${liveTag}`)
}

import httpx

# Python - fetch A1 league entries for Balkans
response = httpx.get(
    'https://tik.tools/api/leaderboards/league/BK/2000',
    headers={'x-api-key': 'YOUR_ULTRA_API_KEY'}
)

data = response.json()

if not data['hasFullAccess']:
    print(f"Teaser mode: {data['maskedCount']} entries hidden. Upgrade to Ultra for full access.")

print(f"A1 Balkans - {data['totalCount']} creators total")

for entry in data['entries']:
    live_tag = ' [LIVE]' if entry['isLive'] else ''
    print(f"#{entry['rank']} @{entry['uniqueId']} - {entry['score']:,} diamonds{live_tag}")

# cURL - fetch A1 league entries for Balkans
curl -s \
  -H "x-api-key: YOUR_ULTRA_API_KEY" \
  "https://tik.tools/api/leaderboards/league/BK/2000" \
  | jq '{
      totalCount: .totalCount,
      hasFullAccess: .hasFullAccess,
      entries: [.entries[] | "#\(.rank) @\(.uniqueId): \(.score) diamonds"]
    }'

// Browser JavaScript - A1 entries from logged-in session
const res = await fetch('/api/leaderboards/league/BK/2000')
const data = await res.json()

console.log(`Full access: ${data.hasFullAccess}`)
console.log(`Showing ${data.entries.length} of ${data.totalCount} creators`)

const liveNow = data.entries.filter(e => e.isLive)
console.log(`${liveNow.length} creators currently streaming live`)

data.entries.forEach(e => {
  console.log(`#${e.rank} ${e.nickname}: ${e.score.toLocaleString()} diamonds${e.isLive ? ' ★' : ''}`)
})

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type LeagueEntry struct {
	Rank     int    `json:"rank"`
	UniqueId string `json:"uniqueId"`
	Nickname string `json:"nickname"`
	Score    int    `json:"score"`
	IsLive   bool   `json:"isLive"`
}

type LeagueResponse struct {
	HasFullAccess bool          `json:"hasFullAccess"`
	MaskedCount   int           `json:"maskedCount"`
	TotalCount    int           `json:"totalCount"`
	Entries       []LeagueEntry `json:"entries"`
}

func main() {
	req, _ := http.NewRequest("GET",
		"https://tik.tools/api/leaderboards/league/BK/2000", nil)
	req.Header.Set("x-api-key", "YOUR_ULTRA_API_KEY")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var data LeagueResponse
	json.NewDecoder(resp.Body).Decode(&data)

	fmt.Printf("A1 Balkans - %d creators (full access: %v)\n", data.TotalCount, data.HasFullAccess)

	for _, e := range data.Entries {
		liveTag := ""
		if e.IsLive {
			liveTag = " [LIVE]"
		}
		fmt.Printf("#%d @%s - %d diamonds%s\n", e.Rank, e.UniqueId, e.Score, liveTag)
	}
}

<?php
// PHP - fetch A1 league entries for Balkans
$context = stream_context_create([
    'http' => ['header' => "x-api-key: YOUR_ULTRA_API_KEY\r\n"]
]);

$json = file_get_contents(
    'https://tik.tools/api/leaderboards/league/BK/2000',
    false, $context
);

$data = json_decode($json, true);

if (!$data['hasFullAccess']) {
    echo "Teaser mode: {$data['maskedCount']} entries hidden.\n";
}

echo "A1 Balkans - {$data['totalCount']} creators\n";

foreach ($data['entries'] as $entry) {
    $live = $entry['isLive'] ? ' [LIVE]' : '';
    $score = number_format($entry['score']);
    echo "#{$entry['rank']} @{$entry['uniqueId']} - {$score} diamonds{$live}\n";
}

// Complete example: Find all A1 creators live in Balkans right now

const BASE = 'https://tik.tools'
const REGION = 'BK'
const HEADERS = { 'x-api-key': 'YOUR_ULTRA_API_KEY' }

async function getA1LiveCreators() {
  // Step 1: Fetch available leagues for Balkans
  const leaguesRes = await fetch(`${BASE}/api/leaderboards/leagues/${REGION}`, {
    headers: HEADERS
  })
  const leagues = await leaguesRes.json()

  // Step 2: Find the A1 class (classType 2000)
  const a1 = leagues.find(l => l.classLabel === 'A1')
  if (!a1) {
    console.log('A1 class not found in Balkans')
    return []
  }

  console.log(`Found A1 class: ${a1.count} creators, last updated ${a1.updatedAt}`)

  // Step 3: Fetch A1 entries
  const entriesRes = await fetch(
    `${BASE}/api/leaderboards/league/${REGION}/${a1.classType}`,
    { headers: HEADERS }
  )
  const data = await entriesRes.json()

  if (!data.hasFullAccess) {
    console.warn(`Only showing ${data.entries.length} of ${data.totalCount} entries (teaser mode)`)
  }

  // Step 4: Filter for creators currently live
  const liveCreators = data.entries.filter(e => e.isLive)

  return liveCreators
}

const live = await getA1LiveCreators()
console.log(`\n${live.length} A1 creator(s) live in Balkans right now:\n`)

for (const creator of live) {
  console.log(`  #${creator.rank} @${creator.uniqueId} - ${creator.score.toLocaleString()} diamonds`)
}

// Connect to their streams via TikTool WebSocket
for (const creator of live) {
  console.log(`  wss://api.tik.tools?uniqueId=${creator.uniqueId}&apiKey=YOUR_API_KEY`)
}

import httpx

# Complete example: Find all A1 creators live in Balkans right now

BASE = 'https://tik.tools'
REGION = 'BK'
HEADERS = {'x-api-key': 'YOUR_ULTRA_API_KEY'}


def get_a1_live_creators():
    # Step 1: Fetch available leagues for Balkans
    leagues_res = httpx.get(f'{BASE}/api/leaderboards/leagues/{REGION}', headers=HEADERS)
    leagues = leagues_res.json()

    # Step 2: Find the A1 class (classType 2000)
    a1 = next((l for l in leagues if l['classLabel'] == 'A1'), None)
    if not a1:
        print('A1 class not found in Balkans')
        return []

    print(f"Found A1 class: {a1['count']} creators, last updated {a1['updatedAt']}")

    # Step 3: Fetch A1 entries
    entries_res = httpx.get(
        f"{BASE}/api/leaderboards/league/{REGION}/{a1['classType']}",
        headers=HEADERS
    )
    data = entries_res.json()

    if not data['hasFullAccess']:
        shown = len(data['entries'])
        total = data['totalCount']
        print(f"Only showing {shown} of {total} entries (teaser mode)")

    # Step 4: Filter for creators currently live
    live_creators = [e for e in data['entries'] if e['isLive']]

    return live_creators


live = get_a1_live_creators()
print(f"\n{len(live)} A1 creator(s) live in Balkans right now:\n")

for creator in live:
    print(f"  #{creator['rank']} @{creator['uniqueId']} - {creator['score']:,} diamonds")

# Connect to their streams via TikTool WebSocket
for creator in live:
    print(f"  wss://api.tik.tools?uniqueId={creator['uniqueId']}&apiKey=YOUR_API_KEY")