HomeLogo

@zikeji/hypixel

NodeJS API wrapper for Hypixel's Public API

Get Started →

Rate Limiting Queue

Built in async rate limiting queue prevents prevents requests from failing by queueing and waiting for the queue to clear.

# @zikeji/hypixel

npm (opens new window) Deno (opens new window) npm bundle size (opens new window) visit docs (opens new window) Visit our Discord server. (opens new window) Snyk Vulnerabilities for npm package version (opens new window) Libraries.io dependency status for latest release (opens new window) GitHub license (opens new window) GitHub last commit (opens new window) GitHub code size in bytes (opens new window) GitHub issues (opens new window) Coveralls (opens new window) GitHub Workflow Status (opens new window)

With thorough IntelliSense (opens new window) support & 100% test coverage (opens new window), this is an unopinionated async/await API wrapper for Hypixel's Public API (opens new window). It is developed in TypeScript complete with documentation (opens new window), typed interfaces (opens new window) for all API responses (and an OpenAPI.yaml (opens new window)!), built-in rate-limit handling, flexible cache support (opens new window), helper functions (opens new window), and support for undocumented endpoints.

This library aims to replicate the API paths in it's method usage. As such, the general scheme would be to change the path of an API call by simply replacing the / with a ., and if the endpoint takes multiple parameters, those are added on the end. For example, api.hypixel.net/skyblock/profiles?uuid=1234 would simply become client.skyblock.profiles.uuid('1234'). Of course, with everything being fully typed if you are using an IDE that supports IntelliSense (opens new window) you should rarely need to reference documentation.

# 2.0 to 3.0 Migration

This library follows semver. As backwards incompatible changes were introduced while making this Deno compatible. Most likely nothing you use has changed, and you should be able to update without issue. The only breaking change is that the Client class no longer accepts agent as a parameter, as Deno does not support this.

# Installation

# NodeJS

Use npm (opens new window) to install this library.

npm i --save @zikeji/hypixel
1

# Deno

As Deno does not require installation, you would simply follow their convention for imports.

import { Client as HypixelClient } from "https://deno.land/x/hypixel/v3.1.0/mod.ts";
1

# Usage

const { Client } = require("@zikeji/hypixel");
const client = new Client("API_KEY");
(async () => {
  const status = await client.status.uuid("20934ef9488c465180a78f861586b4cf"); // Minikloon
  console.log(status);
  // {"online": false}
  const stats = await client.watchdogstats();
  console.log(stats);
  // {watchdog_lastMinute: 1, staff_rollingDaily: 2609, watchdog_total: 5591714, watchdog_rollingDaily: 4213, …}
})();
1
2
3
4
5
6
7
8
9
10

# Helpers

This library adds multiple helpers to facilitate using the Hypixel API. You can find documentation on each helper here (opens new window). If you would like to request a helper that doesn't exist, please open an issue. Otherwise if you would like to contribute one refer to the below section.

# Contributing

If some API result isn't documented / typed out fully, please open an issue and I can see about adding it. However some data is too exhaustive to provide typings to in a reasonable manner, as exhibited here (opens new window), where it isn't reasonable to add 19.5 thousand lines of code to document the entire dataset.

Otherwise, pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. All changes must ensure they pass eslint, tests, and that testing is updated to meet or exceed the previous coverage.

# Licenses

This projected is licensed under the MIT license. For additional details see LICENSE.

This library contains derivative work based on classes from the hypixel-php (opens new window) library. Code that is derivative work of hypixel-php (opens new window) will be marked as such with a header comment. See LICENSE-HYPIXEL-PHP.md for additional details on the original license.