The gateway to Tricktracker data

API Online

Welcome

This is the main page of TrickAPI. Currently, the API base and database connection are configured and ready to receive instructions.

API Key Limits

By default, an API Key does not grant access to any specific endpoints or WebSocket events. You must manually request access to the resources you wish to use.

Level Rate Limit Cooldown
Level 1 100 requests / 5 minutes 10 seconds per request
Level 2 200 requests / 5 minutes 5 seconds per request
Level 3 Unlimited None

Usage Examples

fetch('https://trickapi.duckdns.org/api/ping/EdTrick', {
  headers: { 'API-Key': 'YOUR_API_KEY' }
})
.then(res => res.json())
.then(console.log);
import requests
headers = { 'API-Key': 'YOUR_API_KEY' }
res = requests.get('https://trickapi.duckdns.org/api/ping/EdTrick', headers=headers)
print(res.json())
use reqwest::header;

#[tokio::main]
async fn main() -> Result<(), Box> {
    let client = reqwest::Client::new();
    let res = client.get("https://trickapi.duckdns.org/api/ping/EdTrick")
        .header("API-Key", "YOUR_API_KEY")
        .send()
        .await?;
    let text = res.text().await?;
    println!("{}", text);
    Ok(())
}

WebSockets

TrickAPI provides a real-time WebSocket server using Socket.IO. You must authenticate using your API Key in the handshake.

const io = require('socket.io-client');

const socket = io('https://trickapi.duckdns.org/', {
    auth: {
        key: 'YOUR_API_KEY'
    }
});

socket.on('connect', () => {
    console.log('Connected to TrickAPI');
});

socket.on('ban', (data) => {
    console.log('Ban Detected:', data);
});

Available Events

EVENT ban

Emitted when a player is detected as banned from the Hypixel leaderboards.

{
  "uuid": "00000000-0000-0000-0000-000000000000",
  "name": "EdTrick",
  "prefix": "[1300✫]",
  "bedwarsLevel": 1300,
  "rank": "[MVP+]",
  "duelsTitle": "GODLIKE",
  "skywarsLevel": 15,
  "megaWallsWins": 120,
  "smashHeroesWins": 300,
  "buildBattleTitle": "Seasoned",
  "quakecraftKills": 1476,
  "positions": [
    {
      "gameMode": "BEDWARS",
      "leaderboard": "Weekly Wins",
      "position": 12
    },
    {
      "gameMode": "BEDWARS",
      "leaderboard": "Weekly Final Kills",
      "position": 5
    }
  ],
  "timestamp": 1716503040
}
EVENT lbPositionChanges

Emitted when players improve their positions on the Hypixel leaderboards. (Note: Only applies to Bedwars, Skywars, and Duels Monthly/Weekly leaderboards. Lifetime/Overall leaderboards are ignored).

{
  "oldTimestamp": 1716502980,
  "newTimestamp": 1716503040,
  "players": [
    {
      "uuid": "44dfbd80-00d3-47bf-8ceb-209451055412",
      "name": "oVoidPhobic",
      "rank": "[MVP+]",
      "changes": [
        {
          "mode": "MCGO",
          "leaderboard": "Monthly Defusal Wins",
          "oldPosition": 55,
          "newPosition": 15
        }
      ]
    }
  ]
}
EVENT bwStatsChanges

Emitted when a player's Bedwars statistics change.

{
  "player": "EdTrick",
  "prefix": "[MVP++]",
  "oldTimestamp": 1689528246000,
  "newTimestamp": 1689531846000,
  "changes": [
    {
      "type": "final_kills",
      "mode": "overall",
      "old": 1500,
      "new": 1502
    },
    {
      "type": "beds_broken",
      "mode": "overall",
      "old": 500,
      "new": 501
    },
    {
      "type": "final_deaths",
      "mode": "overall",
      "old": 700,
      "new": 700
    },
    {
      "type": "final_kills",
      "mode": "4v4",
      "old": 200,
      "new": 202
    }
  ]
}
EVENT bwCosmeticsChanges

Emitted when a player changes their Bedwars cosmetics.

{
  "player": "EdTrick",
  "prefix": "[MVP++]",
  "oldTimestamp": 1689528246000,
  "newTimestamp": 1689531846000,
  "changes": [
    {
      "type": "kill_messages",
      "old": "killmessages_default",
      "new": "killmessages_blood"
    },
    {
      "type": "victory_dance",
      "old": "victorydance_none",
      "new": "victorydance_dragon"
    },
    {
      "type": "island_topper",
      "old": "islandtopper_none",
      "new": "islandtopper_dragon"
    }
  ]
}
EVENT bwParty

Emitted when a Bedwars party status changes.

{
  "host": {
    "username": "EdTrick",
    "prefix": "[MVP++]"
  },
  "timestamp": 1689531846000,
  "messages": [
    {
      "timestamp": 1689531825000,
      "lobbyId": 1,
      "content": "1/4 p me"
    },
    {
      "timestamp": 1689531830000,
      "lobbyId": 1,
      "content": "1/4 need fast players"
    }
  ],
  "requesters": [
    {
      "username": "CoolPlayer",
      "prefix": "[MVP+]"
    },
    {
      "username": "NoobMaster",
      "prefix": "[VIP]"
    },
    {
      "username": "Tryhard",
      "prefix": "[MVP++]"
    }
  ],
  "possibleMembers": [
    {
      "username": "CoolPlayer",
      "prefix": "[MVP+]",
      "diffSeconds": -0.42,
      "lobbyId": 1
    },
    {
      "username": "NoobMaster",
      "prefix": "[VIP]",
      "diffSeconds": 1.25,
      "lobbyId": 1
    }
  ]
}
EVENT coralTag

Emitted when a Coral tag is added, removed, or overwritten for a player.

{
  "action": "Add",
  "ign": "TargetPlayer",
  "uuid": "00000000-0000-0000-0000-000000000000",
  "review": "https://discord.com/channels/1339318572069158962/1532234083726524619",
  "evidence": "https://discord.com/channels/1339318572069158962/1533638558416637962",
  "pinged": ["1251676780595515456", "1191378300912808028"],
  "tags": [
    {
      "type": "Sniper",
      "reason": "Queue dodging and targeting",
      "tagger": "Moderator123",
      "timestamp": 1716503040
    }
  ]
}
EVENT denick

(Currently Unavailable) Emitted in real-time when one or more nicked players are detected and denicked. A single event can contain multiple detections.

{
  "denicks": [
    {
      "realName": "EdTrick",
      "gamemode": "Murder Mystery (Classic)",
      "nick": "SomeFakeNick",
      "timestamp": 1716503040
    },
    {
      "realName": "javadevs",
      "gamemode": "Skywars (Mini)",
      "nick": "AnotherNick",
      "timestamp": 1716503045
    }
  ]
}
EVENT unban

Emitted when a previously banned player is detected as active again on the Hypixel leaderboards, closing the ban record.

{
  "timestamp": 1788016858,
  "uuid": "39d730b5c7e34d179902f52c1e889bfc",
  "username": "EdTrick",
  "modes": [
    {
      "mode": "BEDWARS",
      "positions": [
        {
          "path": "wins",
          "prefix": "Wins",
          "position": 22
        },
        {
          "path": "final_kills",
          "prefix": "Final Kills",
          "position": 12
        }
      ]
    }
  ],
  "bannedAt": 1785403763,
  "unbannedAt": 1788016858
}

Available Endpoints

GET /api

Base endpoint to check API status.

{
  "message": "Welcome to TrickAPI",
  "status": "online"
}
GET /api/bw-denick

Search for nicked MVP++ or YOUTUBE players by timestamp, mode, stats and cosmetics. Requires the API-Key header.

Parameter Type Status Description
timestamp Integer Optional Unix timestamp in seconds. Required if duration or mode is used.
mode String Optional Valid values: 1s, 2s, 3s, 4s, 4v4. Comma-separated for multiple.
duration String Optional Match duration in MM:SS or HH:MM:SS format. Requires timestamp.
time_range Integer Optional Margin in minutes for the timestamp search (default: 2, max: 300). Auto-sets timestamp to now if omitted.
final_kills Integer Optional Player's final kills. stats_range applies.
beds_broken Integer Optional Player's beds broken. stats_range applies.
stats_range Integer Optional Margin for stat matching (default: 100).
recently_online Boolean Optional Filter to players seen in the last 24h (default: true). Only applies when no timestamp is given.
exact_match Boolean Optional Ignore random_cosmetic / random_favorite_cosmetic matches (default: false).
[cosmetic] String / Array Optional Cosmetic filter. Accepted keys: kill_effect, victory_dance, kill_messages, island_topper, npc_skin, glyph, bed_destroy, wood_type, figurine.
Comma-separate multiple values. Append EXACT_MATCH to a cosmetic's value list to force strict matching for that slot. Append INVISIBLE (only for kill_effect / bed_destroy) to match visually-invisible effects. 
{
  "matches": 1,
  "players": [
    {
      "player_name": "example_player",
      "uuid": "00000000-0000-0000-0000-000000000000",
      "finals": 1500,
      "beds": 800,
      "score": 10500.1,
      "record_timestamp": 1716503040000,
      "last_seen": {
        "activity_type": "bw lobby 12 leave",
        "timestamp": 1716503000000
      },
      "cosmetics": {
        "killmessages": "killmessages_dramatic",
        "victorydance": "victorydance_dragon_rider",
        "killeffect": "killeffect_blood_explosion",
        "islandtopper": "islandtopper_dragon",
        "npcskin": "npcskin_villager",
        "glyph": "glyph_diamond",
        "beddestroy": "beddestroy_pig",
        "woodSkin": "woodSkin_oak",
        "figurine": "figurine_steve"
      }
    }
  ]
}
{
  "error": "Unauthorized",
  "message": "API Key is missing."
}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded.",
  "timeRemainingMs": 45000
}
GET /api/bw-qt-denick

Find a nicked player (J2) by matching lobby join/leave events with a known player (J1) AND filtering by cosmetics/stats. Requires an authorized API-Key.

Parameter Type Status Description
player_name String Required Primary player name (J1) to match events against.
timestamp Integer Optional Center Unix timestamp in seconds (default: now).
time_range Integer Optional Window in minutes around the timestamp to search (default: 20, max: 300).
max_diff Integer Optional Maximum difference in seconds between J1 and J2 events (default: 3).
mode String Optional Valid values: 1s, 2s, 3s, 4s, 4v4.
final_kills Integer Optional J2's final kills. stats_range applies.
beds_broken Integer Optional J2's beds broken. stats_range applies.
stats_range Integer Optional Margin for stat matching (default: 100).
exact_match Boolean Optional Ignore random cosmetic matches (default: false).
[cosmetic] String / Array Optional At least one cosmetic or stat is required.
Accepted keys: kill_effect, victory_dance, kill_messages, island_topper, npc_skin, glyph, bed_destroy, wood_type, figurine.
Supports EXACT_MATCH and INVISIBLE per slot. 
{
  "j1": "EdTrick",
  "center_timestamp": 1716503040,
  "time_range_minutes": 20,
  "max_diff_seconds": 3,
  "matches": 2,
  "candidates": [
    {
      "player_name": "NickedPlayer",
      "coincidences": 4,
      "coincidence_timestamps": [1716502980, 1716503010, 1716503060, 1716503120],
      "coincidence_diffs_s": [-1.2, 0.5, 2.1, -0.8],
      "finals": 2340,
      "beds": 980,
      "record_timestamp": 1716503000000,
      "cosmetics": {
        "killmessages": "killmessages_dramatic",
        "victorydance": "victorydance_dragon_rider",
        "killeffect": "killeffect_blood_explosion",
        "islandtopper": "islandtopper_dragon",
        "npcskin": "npcskin_villager",
        "glyph": "glyph_diamond",
        "beddestroy": "beddestroy_pig",
        "woodSkin": "woodSkin_oak",
        "figurine": "figurine_steve"
      }
    }
  ]
}
{
  "error": "Forbidden",
  "message": "This endpoint requires a Level 2 (or higher) API key."
}
{
  "error": "Unauthorized",
  "message": "API Key is missing."
}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded.",
  "timeRemainingMs": 45000
}
GET /api/ping/:player

Get the ping history for a specific player (top 20 results). Requires the API-Key header.

Parameter Type Status Description
:player String Required Target player's username or UUID (URL path parameter). 
{
  "player": "notch",
  "records_count": 2,
  "data": [
    { "ping": 45, "record_timestamp": 1716503040000 },
    { "ping": 48, "record_timestamp": 1716502040000 }
  ]
}
{
  "error": "Forbidden",
  "message": "Invalid API Key."
}
{
  "error": "Too Many Requests",
  "message": "Cooldown active.",
  "timeRemainingMs": 8500
}
GET /api/bw-cosmetics/:player

Get the cosmetics history for a specific player. Requires the API-Key header.

Parameter Type Status Description
:player String Required Target player's username or UUID (URL path parameter).
timestamp Integer Optional Center Unix timestamp in seconds to fetch records around (URL query parameter). 
{
  "player": "notch",
  "records_count": 1,
  "data": [
    {
      "timestamp": 1716503040000,
      "active": {
        "killmessages": "killmessages_blood",
        "victorydance": "victorydance_dragon_rider",
        "killeffect": "killeffect_blood_explosion",
        "islandtopper": "islandtopper_dragon",
        "npcskin": "npcskin_villager",
        "glyph": "glyph_diamond",
        "beddestroy": "beddestroy_pig",
        "woodSkin": "woodSkin_oak",
        "figurine": "figurine_steve"
      },
      "owned": {
        "killmessages": ["killmessages_blood", "killmessages_dramatic"],
        "victorydance": ["victorydance_dragon_rider", "victorydance_meteor"],
        "killeffect": ["killeffect_blood_explosion", "killeffect_heart"],
        "islandtopper": ["islandtopper_dragon", "islandtopper_sloth"],
        "npcskin": ["npcskin_villager", "npcskin_zombie"],
        "glyph": ["glyph_diamond", "glyph_emerald"],
        "beddestroy": ["beddestroy_pig", "beddestroy_squid"],
        "woodSkin": ["woodSkin_oak", "woodSkin_birch"],
        "figurine": ["figurine_steve", "figurine_alex"],
        "projectiletrail": ["projectiletrail_flame"],
        "deathcry": ["deathcry_dinosaur"],
        "sprays": ["sprays_gg"]
      },
      "favorites": {
        "killmessages": ["killmessages_blood"],
        "victorydance": ["victorydance_dragon_rider"]
      }
    }
  ]
}
{
  "error": "Forbidden",
  "message": "Invalid API Key."
}
GET /api/bw-stats/:player

Get the stats history for a specific player. Requires the API-Key header.

Parameter Type Status Description
:player String Required Target player's username or UUID (URL path parameter).
timestamp Integer Optional Center Unix timestamp in seconds to fetch records around (URL query parameter). 
{
  "player": "notch",
  "records_count": 1,
  "data": [
    {
      "timestamp": 1716503040000,
      "stats": {
        "overall": {
          "final_kills": 1000,
          "final_deaths": 500,
          "beds_broken": 250,
          "beds_lost": 125,
          "wins": 300,
          "losses": 150,
          "kills": 4000,
          "deaths": 2000,
          "magic_deaths": 10
        },
        "1s": {
          "final_kills": 200,
          "final_deaths": 100,
          "beds_broken": 50,
          "beds_lost": 25,
          "wins": 60,
          "losses": 30,
          "kills": 800,
          "deaths": 400,
          "magic_deaths": 2
        },
        "2s": {
          "final_kills": 200,
          "final_deaths": 100,
          "beds_broken": 50,
          "beds_lost": 25,
          "wins": 60,
          "losses": 30,
          "kills": 800,
          "deaths": 400,
          "magic_deaths": 2
        },
        "3s": {
          "final_kills": 200,
          "final_deaths": 100,
          "beds_broken": 50,
          "beds_lost": 25,
          "wins": 60,
          "losses": 30,
          "kills": 800,
          "deaths": 400,
          "magic_deaths": 2
        },
        "4s": {
          "final_kills": 200,
          "final_deaths": 100,
          "beds_broken": 50,
          "beds_lost": 25,
          "wins": 60,
          "losses": 30,
          "kills": 800,
          "deaths": 400,
          "magic_deaths": 2
        },
        "4v4": {
          "final_kills": 200,
          "final_deaths": 100,
          "beds_broken": 50,
          "beds_lost": 25,
          "wins": 60,
          "losses": 30,
          "kills": 800,
          "deaths": 400,
          "magic_deaths": 2
        }
      }
    }
  ]
}
{
  "error": "Forbidden",
  "message": "Invalid API Key."
}
GET /api/player-data

Fetch player information by providing a comma-separated list of UUIDs or usernames. Requires the API-Key header.

Parameter Type Status Description
search String Required Comma-separated list of UUIDs (with or without dashes) or usernames. Max 25 players. (URL query parameter). 
{
  "success": true,
  "count": 2,
  "data": [
    {
      "uuid": "39d730b5-c7e3-4d17-9902-f52c1e889bfc",
      "name": "SomeName",
      "rank": "MVP+",
      "timestamp": 1693125200
    },
    {
      "uuid": "8e0fd8aa-9342-43ea-a577-9410a0c4edce",
      "name": "Kalehmm",
      "rank": "VIP",
      "timestamp": 1693125400
    }
  ]
}
{
  "success": false,
  "message": "Could not retrieve information for any of the requested players."
}
{
  "error": "Bad Request",
  "message": "A maximum of 25 players can be requested at once."
}
{
  "error": "Forbidden",
  "message": "Invalid API Key."
}
GET /api/tricklist/view-tags

Fetch Tricklist tags for one or more players by providing a comma-separated list of UUIDs or usernames. Requires the API-Key header.

Parameter Type Status Description
search String Required Comma-separated list of UUIDs (with or without dashes) or usernames. Max 16 players. (URL query parameter). (You can also use name or uuid instead of search) 
[
  {
    "mc_uuid": "39d730b5-c7e3-4d17-9902-f52c1e889bfc",
    "mc_name": "EdTrick",
    "tag_type": "Info",
    "reason": "test",
    "tagger_discord_id": "405958241202339840",
    "tagger_discord_name": "edtrick",
    "added_at": 1788436891,
    "evidence_thread_id": null,
    "evidence_post_url": null,
    "staff_discord_id": null,
    "staff_discord_name": null,
    "confirmed": false
  }
]
{
  "error": "Bad Request",
  "message": "A maximum of 16 players can be requested at once."
}
{
  "error": "Forbidden",
  "message": "Invalid API Key."
}