TrickAPI
The gateway to Tricktracker data
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 | 30 requests / 5 minutes | 10 seconds per request |
| Level 2 | 60 requests / 5 minutes | 5 seconds per request |
| Level 3 | Unlimited | None |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
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
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
}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
}
]
}
]
}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
}
]
}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"
}
]
}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
}
]
}Emitted when a Coral tag is added, removed, or overwritten for a player.
{
"action": "Add",
"ign": "TargetPlayer",
"bedwarsLevel": 41,
"fkdr": 28.04,
"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
}
]
}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
}
]
}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
}Exclusive Emitted in real-time when a new Bedwars queue match is detected and registered.
{
"queueId": 1670,
"server": "mini78AQ",
"map": "Witch's Bog",
"mode": "BEDWARS_FOUR_THREE",
"timestamp": 1793655214.24,
"teams": [
{
"color": "red",
"nicks": 1,
"players": [
{
"uuid": "20d1335c-7cd9-422f-956e-dfd162e09304",
"name": "NiitroOo",
"nicked": false,
"realIGN": null
},
{
"uuid": null,
"name": "thenatepapa",
"nicked": true,
"realIGN": null
}
]
},
{
"color": "blue",
"nicks": 0,
"players": [
{
"uuid": "a7c3950e-c22f-4100-944b-84fe2c9b5af2",
"name": "OnyGooD",
"nicked": false,
"realIGN": null
}
]
}
],
"replay": null
}Exclusive Emitted in real-time when a replay command and ID are recorded for a Bedwars queue match.
{
"queueId": 1001,
"server": "mini101A",
"map": "Speedway",
"mode": "BEDWARS_FOUR_FOUR",
"timestamp": 1730663600.789,
"replay": "3e9b114d-fa33-4089-a2e6-7b47b4d1b09b #10:20",
"replayCommand": "/replay 3e9b114d-fa33-4089-a2e6-7b47b4d1b09b #10:20",
"notablePlayers": [
{
"nick": "Sa1ty_Jedi",
"name": "DAERPY",
"uuid": "a9ed06b6-7792-4f4b-ac87-67263debb948",
"stars": 949,
"fkdr": 28.03,
"nicked": true
},
{
"nick": "Xx_Cool_Cam_xX",
"name": "4jz_",
"uuid": "dd6f8d23-4e92-4d92-8389-85f8b691d456",
"stars": 52,
"fkdr": 3.64,
"nicked": true
},
{
"nick": null,
"name": "Manhal_IQ_",
"uuid": "022d8e4f-26ec-4f24-9b8e-d9ff2317135e",
"stars": 4389,
"fkdr": 12.34,
"nicked": false
}
]
}Exclusive Emitted in real-time when nicked players in a Bedwars queue match are revealed (denicked).
{
"queueId": 1670,
"server": "mini78AQ",
"map": "Witch's Bog",
"mode": "BEDWARS_FOUR_THREE",
"timestamp": 1793655580.89,
"denicks": [
{
"id": 721,
"nick": "thenatepapa",
"realIGN": "IljaK04",
"uuid": "9ea181f7-4ba6-45d5-9b6b-06f66dec1b90"
}
],
"teams": [
{
"color": "red",
"nicks": 1,
"players": [
{
"uuid": "20d1335c-7cd9-422f-956e-dfd162e09304",
"name": "NiitroOo",
"nicked": false,
"realIGN": null
},
{
"uuid": "9ea181f7-4ba6-45d5-9b6b-06f66dec1b90",
"name": "thenatepapa",
"nicked": true,
"realIGN": "IljaK04"
}
]
},
{
"color": "blue",
"nicks": 0,
"players": [
{
"uuid": "a7c3950e-c22f-4100-944b-84fe2c9b5af2",
"name": "OnyGooD",
"nicked": false,
"realIGN": null
}
]
}
]
}Available Endpoints
Base endpoint to check API status.
{
"message": "Welcome to TrickAPI",
"status": "online"
}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 ormode 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. Requirestimestamp. |
| 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_cosmeticmatches (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. |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
{
"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
}VIP 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. |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
{
"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 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). |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
{
"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 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). |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
{
"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 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). |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
{
"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."
}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). |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
{
"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."
}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) |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
[
{
"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."
}VIP Search for denick records by nick, real IGN, or UUID in Bedwars queues. Requires an authorized API-Key.
| Parameter | Type | Status | Description |
|---|---|---|---|
| search | String | Required | Nick, real IGN, or UUID to search (URL query parameter). |
| limit | Integer | Optional | Maximum number of records to return (default: 100, max: 100). Ignored for Level 1 keys (returns at most 1 record). |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
{
"success": true,
"search": "FoxyDreamKid",
"records_count": 1,
"data": [
{
"id": 6,
"timestamp": 1792539811.27,
"nick": "FoxyDreamKid",
"realIGN": "CDG_AF1",
"uuid": "926bbe1c-53fc-439b-9ef2-b5d17063d664"
}
]
}{
"success": false,
"message": "No denick records found for \"RandomNick\" in Bedwars queues."
}{
"error": "Bad Request",
"message": "The \"search\" query parameter is required (nick, real IGN, or UUID)."
}{
"error": "Forbidden",
"message": "Your API key does not have access to this endpoint (findnick)."
}VIP View Bedwars queue match history filtered by player, map, mode, or nick. Replays are kept private and never exposed. Requires an authorized API-Key.
| Parameter | Type | Status | Description |
|---|---|---|---|
| player | String | Filter* | Filter queues where this player participated (username, real IGN, or UUID). |
| nick | String | Filter* | Filter queues by nick name used in match. |
| map | String | Filter* | Filter queues by map name (e.g. Aquarium, Rooftop). |
| mode | String | Filter* | Filter queues by Bedwars mode (e.g. eight_two, four_four, 1s, 2s). |
| limit | Integer | Optional | Maximum number of records to return (default: 100, max: 100). |
* Note: Level 1 keys have specific time-window and probability restrictions on /api/findnick (returning at most 1 latest record). See endpoint documentation for details.
* At least one filter option must be provided: player, nick, map, or mode.
{
"success": true,
"count": 1,
"filters": {
"player": "shayhacker",
"map": null,
"mode": null,
"nick": null
},
"data": [
{
"id": 8,
"timestamp": 1792539451.448,
"map": "Aquarium",
"server": "mini193CP",
"mode": "BEDWARS_FOUR_FOUR",
"teams": [
{
"color": "yellow",
"nicks": 0,
"players": [
{
"name": "shayhacker",
"uuid": "54d1c1ed-ad44-4c3f-8829-c560c9916b76",
"nicked": false,
"realIGN": null
}
]
}
]
}
]
}{
"success": false,
"message": "No queue records found matching your filters."
}{
"error": "Bad Request",
"message": "You must provide at least one filter option: player, map, mode, or nick."
}{
"error": "Forbidden",
"message": "Your API key does not have access to this endpoint (queues)."
}