Hypicle v1.1.4

Hypicle on NPM

How to get the API Key?

1. Visit the Hypixel Developer Dashboard.
2. Log in.
3. Generate and Copy a new Development Key.

Quick Start

import { Hypicle } from 'hypicle';

const client = new Hypicle('YOUR_API_KEY');

Hypicle Structure

• api/

  • api/boosters - Currently active boosters
  • api/counts - Active players count
  • api/guild - Guild information
  • api/key - API Key information (deprecated)
  • api/leaderboards - Global Leaderboards information
  • api/player - Player information & statistics
  • api/punishments - Punishment statistics
  • api/recentgames - Recent games of a player
  • api/status - Status of a player

• client.ts - The Hypicle Client

• utils.ts - The Hypicle Utils

Hypixel API implementation in Hypicle

This is the Hypixel API implementation.

Below you can find a list of available API endpoints in Hypicle.

All endpoints require the Hypicle client, and some endpoints require additional information like player uuid.

Implemented API endpoints

• boosters - Currently active boosters
• counts - Active players count
• guild - Guild information
• key - Key information (deprecated)
• leaderboards - Global Leaderboards information
• player - Player information & statistics
• punishments - Punishment statistics
• recentgames - Recent games of a player
• status - Status of a player

Boosters Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/boosters

This endpoint returns all Active Network Boosters

Usage

Example:

const boosters = await getBoosters(client);
// result: 'Boosters' interface with data

Counts Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/counts

This endpoint returns Current Player Count Status.

Usage

Example:

const counts = await getCounts(client);
// result: 'Counts' interface with data

Other functions

This endpoint also implements game/lobby specific getters.

List of all getters:

• getCounts - Get global active players count statistics
• getMainLobby - Get active players count statistics in Main Lobby
• getTournamentLobby - Get active players count statistics in Tournament Lobby
• getSMP - Get active players count statistics in SMP Servers
• getLegacy - Get active players count statistics in Legacy Games
• getSkywars - Get active players count statistics in SkyWars
• getPit - Get active players count statistics in Pit
• getBuildBattle - Get active players count statistics in Build Battle
• getReplay - Get active players count statistics in Replays
• getWalls - Get active players count statistics in Walls
• getSuperSmash - Get active players count statistics in Smash Heroes
• getBedwars - Get active players count statistics in BedWars
• getArcade - Get active players count statistics in Arcade Games
• getMurderMystery - Get active players count statistics in Murder Mystery
• getUhc - Get active players count statistics in UHC
• getWoolGames - Get active players count statistics in Wool Wars
• getSpeedUhc - Get active players count statistics in Speed UHC
• getHousing - Get active players count statistics in Housing
• getDuels - Get active players count statistics in Duels
• getTntGames - Get active players count statistics in TNT Games
• getBattleground - Get active players count statistics in Warlords
• getSurvivalGames - Get active players count statistics in Survival Games
• getSkyblock - Get active players count statistics in SkyBlock
• getPrototype - Get active players count statistics in Prototype Games
• getMCGO - Get active players count statistics in Cops and Crims
• getLimbo - Get active players count statistics in Limbo
• getIdle - Get active Idle players count statistics
• getQueue - Get active players count statistics in Queue

Guild Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/guild

This endpoint returns Guild data by a player, name or id

Usage

Create a new Guild object with client, id and guild type.

Example:

const guild = new Guild(client, 'guild name', 'name');

Other functions

List of all Guild methods:

• getGuildData - Get the guild data and cache it to a variable
• get - Get the guild
• getID - Get the ID of the guild
• getName - Get the guild name
• getNameLower - Get the guild name in lower case
• getDescription - Get the description of the guild
• getCreatedAt - Get the guild creation timestamp
• isJoinable - Check if the guild is joinable
• isPubliclyListed - Check if the guild is publicly listed
• getExperience - Get experience of the guild
• getLevel - Get the level of the guild (see Leveling)
• getTag - Get the guild tag
• getTagColor - Get the guild tag color
• getLegacyRanking - Get the guild legacy ranking
• getCoins - Get guild coins amount
• getCoinsEver - Get the guild coins ever amount
• getMembersCount - Get the members count of the guild
• getMembers - Get the members list of the guild
• getAchievements - Get the achievements of the guild
• getPreferredGames - Get preferred games of the guild
• getExpByGame - Get the guild experience by game type

Leveling

Guild has its own leveling system.

See Guild Leveling system implementation by Plancke.

You can use GuildLeveling in your project.

List of all GuildLeveling methods:

• getLevel - Get guild level by provided experience

Key Endpoint implementation

This endpoint is no longer available

Hypixel API Endpoint: api.hypixel.net/key

This endpoint returns the API key data.

Usage

Example:

const key = await getKey(client);
// result: 'Key' interface with data

Leaderboards Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/leaderboards

This endpoint returns Current Leaderboards

Usage

Example:

const leaderboards = await getLeaderboards(client);
// result: 'Leaderboards' interface with data

Other functions

This endpoint also implements game/lobby specific getters.

Game/Lobby specific getter returns Leaderboard[].

List of all getters:

• getLeaderboards - Get global Leaderboards statistics
• getLeaderboardsDuels - Get global Duels Leaderboards statistics
• getLeaderboardsTrueCombat - Get global Crazy Walls Leaderboards statistics
• getLeaderboardsSpeedUhc - Get global SpeedUHC Leaderboards statistics
• getLeaderboardsPaintball - Get global Paintball Leaderboards statistics
• getLeaderboardsMurderMystery - Get global Murder Mystery Leaderboards statistics
• getLeaderboardsSkywars - Get global SkyWars Leaderboards statistics
• getLeaderboardsBedwars - Get global BedWars Leaderboards statistics
• getLeaderboardsPrototype - Get global Prototype Leaderboards statistics
• getLeaderboardsGingerbread - Get global Turbo Kart Racers Leaderboards statistics
• getLeaderboardsWoolGames - Get global Wool Wars Leaderboards statistics
• getLeaderboardsTntGames - Get global TNT Games Leaderboards statistics
• getLeaderboardsUhc - Get global UHC Leaderboards statistics
• getLeaderboardsBuildBattle - Get global Build Battle Leaderboards statistics
• getLeaderboardsWalls3 - Get global Mega Walls Leaderboards statistics
• getLeaderboardsVampirez - Get global VampireZ Leaderboards statistics
• getLeaderboardsArcade - Get global Arcade Leaderboards statistics
• getLeaderboardsWalls - Get global Walls Leaderboards statistics
• getLeaderboardsSurvivalGames - Get global Survival Games Leaderboards statistics
• getLeaderboardsSuperSmash - Get global Smash Heroes Leaderboards statistics
• getLeaderboardsSkyclash - Get global SkyClash Leaderboards statistics
• getLeaderboardsQuakecraft - Get global Quake Leaderboards statistics
• getLeaderboardsMCGO - Get global Cops and Crims Leaderboards statistics
• getLeaderboardsBattleground - Get global Warlords Leaderboards statistics
• getLeaderboardsArena - Get global Arena Leaderboards statistics

Player Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/player

This endpoint returns the player data by uuid

Usage

Create a new Player object with client and uuid.

const player = new Player(client, 'uuid');

Other functions

List of all Player methods:

• getPlayerData - Get the player data and cache it to a variable
• get - Get the player
• getUUID - Get the UUID of the player
• getStatus - Get the status of the player
• getKarma - Get the karma of the player
• getNetworkExp - Get the network experience of the player
• getLevel - Get the network level of the player
• getExactLevel - Get exact network level of the player
• getGuild - Get the guild membership of the player or null
• isStaff - Check if the player is in the staff team
• getHighestRank - Get the highest rank of the player
• getPlusColor - Get the rank plus color
• getName - Get the display name of the player
• getRecentGameType - Get recently played games by the player
• getSocialMedia - Get player connected social media
• getStats - Get the player Stats

Get stats of the player:

const stats = player.getStats();

Get any minigame stats

const minigame = stats.getByName('name');

List of all Stats methods:

• get - Get all minigame stats
• getByName - Get one minigame stats by the name
• getBedwars - Get BedWars-specific stats
• getSkyWars - Get SkyWars-specific stats

BedWars & SkyWars

Due to the complexity of both minigames, you can get specific stats.

Examples:

• BedWars

  const bedwars = stats.getBedwars();
  

• SkyWars

  const skywars = stats.getSkyWars();
  

List of all BedwarsMinigame methods:

• get - Get all the BedWars stats
• getCoins - Get BedWars coins
• getLevel - Get BedWars level (see Leveling)
• getIronCollected - Get collected Iron
• getGoldCollected - Get collected Gold
• getDiamondsCollected - Get collected Diamonds
• getEmeraldsCollected - Get collected Emeralds
• getWinstreak - Get the current winstreak
• getKills - Get BedWars Kills
• getFinalKills - Get BedWars final Kills
• getDeaths - Get BedWars Deaths
• getFinalDeaths - Get BedWars final Deaths
• getWins - Get BedWars wins
• getLosses - Get BedWars losses
• getBedsBroken - Get broken beds amount

List of all SkyWarsMinigame methods:

• get - Get all the SkyWars stats
• getCoins - Get SkyWars coins
• getLevel - Get SkyWars level (see Leveling)
• getSouls - Get all souls
• getSoulsGathered - Get souls gathered
• getSoulWellUses - Get uses of the soul well
• getSoullWellLegendaries - Get the legendary drops from the soul well
• getSoulWellRares - Get the rare drops from the soul well
• getChestsOpened - Get the amount of opened chests
• getBlocksBroken - Get the amount of broken blocks
• getBlocksPlaced - Get the amount of placed blocks
• getEggs - Get the amount of thrown Eggs
• getEnderpearls - Get the amount of thrown Enderpearls
• getArrowsShot - Get the amount of shot arrows
• getArrowsHit - Get the amount of arrows that hit
• getWinstreak - Get the current winstreak
• getKills - Get SkyWars Kills
• getVoidKills - Get SkyWars void Kills
• getAssists - Get SkyWars Assists
• getDeaths - Get SkyWars Deaths
• getWins - Get SkyWars wins
• getLosses - Get SkyWars losses
• getHeads - Get the amount of collected heads
• getHeadCollection - Get the head collection

Leveling

Player has its own leveling system.

See Player Leveling system implementation by Plancke.

You can use PlayerLeveling in your project.

List of all PlayerLeveling methods:

• getExactLevel - Get exact network level by provided experience
• getLevel - Get network level by provided experience
• getPercentageToNextLevel - Get percentage to the next level
• getTotalExpToLevel - Get the experience needed to reach provided level
• getTotalExpToFullLevel - Get the total experience needed to reach provided level

Both BedWars and SkyWars also have their own leveling system.

See SkyWars & BedWars Leveling system implementation by Plancke.

You can also use both BedwarsLeveling & SkyWarsLeveling in your project.

List of all BedwarsLeveling methods:

• getLevelByExp - Get BedWars Level by provided experience
• getExpByLevel - Get BedWars Experience by provided Level

List of all SkyWarsLeveling methods:

• getProgressCurrentLevel - Get the progress of the current level
• getLevelByExp - Get SkyWars Level by provided experience
• getExpByLevel - Get SkyWars Experience by provided Level

Punishments Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/punishmentstats

This endpoint returns global Punishment Statistics

Usage

Example:

const punishments = await getPunishments(client);
// result: 'Punishments' interface with data

Recent Games Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/recentgames

This endpoint returns Recently played games of a specific player by uuid

Usage

Example:

const recentgames = await getRecentgames(client, 'uuid');
// result: 'Recentgames' interface with data

Status Endpoint implementation

Hypixel API Endpoint: api.hypixel.net/status

This endpoint returns the Current Online status of a player by uuid

Usage

Example:

const status = await getStatus(client, 'uuid');
// result: 'Status' interface with data

Hypicle Client

The Hypicle Client is the main entry point to interact with the Hypixel API.

To use the client, you need to construct it with your API Key.

Constructing the Client

To create a new Hypicle Client instance, you can follow the steps below:

import { Hypicle } from 'hypicle';

const client = new Hypicle('YOUR_API_KEY');

How to get the API Key

Fetching an endpoint

Hypicle already provides implementation for some endpoints, see Hypicle Structure.

The Hypicle Client implements two fetching methods.

1. fetch method:

   The fetch method fetches data from the Hypixel API without applying any mappings, it also checks for any errors and then returns the fetched data.

   Parameters:

   • endpoint (string, required) - The endpoint to fetch data from.
   • options (Options, optional) - Optional URL parameters for the request.

2. fetchMapping method:

   The fetchMapping method uses the fetch method, it takes a FieldMap<R> as one of the parameters, then maps the API response to the provided mapping.

   Parameters:

   • endpoint (string, required) - The endpoint to fetch data from.
   • mapping (FieldMap<R>, required) - The map to apply to the fetched data.
   • options (Options, optional) - Optional URL parameters for the request.

Both methods are async and use Promises.

Example:

async function callEndpoint<R extends unknown>(client: Client): Promise<R> {
  return await client.fetch<R>('endpoint');
}

Error handling

When Hypixel API fails then Hypicle catches it and throws a custom error interface.

The HypicleError interface provides useful information about the error like a message, status code, throttle, and if the throttle is global.

Example error throw:

throw new HypicleError('Invalid API Key', 403, false);

Hypicle Utils

This is an internal extension for the Hypicle Client.

You don't need to use any of the utils functions in your code.

Functions

1. searchParamsFromObj function:

   This utility function converts an object with query params to a URLSearchParams object.

   Parameters:

   • obj (T extends Record<String, QueryParam>) - The object with query params to convert

   Returns URLSearchParams object with the query params.

   Example:

   const query: QueryParams = { uuid: '12345', name: 'john' };
   const result = searchParamsFromObj(query); 
   // result: URLSearchParams { 'uuid' => '12345', 'name' => 'john' }
   

2. convertKeysToLowerCase function:

   This utility function converts all keys in an object to lowercase.

   Parameters:

   • data (any) - The source object to convert.

   Returns a new object with all keys converted to lowercase.

   Example:

   const src = { Name: 'john', Age: 30 };
   const result = convertKeysToLowerCase(src);
   // result: { name: 'john', age: 30 }
   

3. mapObjectFields function:

   This utility function applies provided FieldMap to an object.

   Parameters:

   • data (any) - The source object to be mapped.
   • mapping (FieldMap<R extends unknown>) - The object mapping.

   Returns a new object with all properties transformed based on the mapping.

   Example:

   interface SomeType {
     uuid: string,
     username: string,
     age: number,
   }
   
   const obj = {_userid: 123, nickname: 'johndoe1', yearsold: 30};
   const mapping: FieldMap<SomeType> = {
     _userid: 'uuid',
     nickname: 'username',
     yearsold: 'age'
   };
   
   const result = mapObjectFields(obj, mapping);
   // result: { uuid: 123, username: 'johndoe1', age: 30 }