Getting Started

@breezil/hypixel-api is a fully open-source TypeScript library: a typed client for the Hypixel API. It owns the parts that are easy to get wrong: fetching, a TTL cache with single-flight de-duplication, a header-driven rate-limit gate, per-player cooldown handling, and a stall-proof request path. Every response is parsed into strict-raw typed objects and enriched with an always-on .computed namespace of derived values. Config and the name to UUID resolver are injected, so the client runs standalone or embedded.

Install

You will need Node.js >=20 and a Hypixel API key for most endpoints.

npm install @breezil/hypixel-api

Getting your keys

Hypixel API key. Sign in at the Hypixel Developer Dashboard and create a development key. That is the apiKey you pass to the client; without it, endpoint methods return null. Two things to know about how Hypixel keys work:

• Development keys are temporary: they expire after a few days, so you have to regenerate them on the dashboard while developing. They come with the default rate limit (300 requests per 5 minutes), which this client's rate-limit gate reads from the response headers and respects automatically.
• If you do not want to keep regenerating keys, apply for a personal (production) key on the same dashboard: create an app, describe what you are building, and submit it for review. Approved keys do not expire and can be granted higher rate limits.

Aurora API key (optional, only for ping()). The ping() method uses the Aurora API by Bordic, which needs its own key:

1. Add the Vega Discord bot.
2. Run the /api view command on it.
3. Copy the plain Aurora API Key from the reply (the bare key, not the Cubelify URL it also shows).
4. Pass it as the pingApiKey config option.

Everything except ping() works without an Aurora key.

The raw parsed types live in @breezil/hypixel-parsers, which is re-exported here.

Quick Start

import { HypixelClient } from "@breezil/hypixel-api";

const hypixel = new HypixelClient("YOUR-API-KEY");

const player = await hypixel.player.get("Technoblade");
if (player) {
  console.log(player.computed.level.level); // network level from XP
  console.log(player.computed.rank); // display rank, e.g. "MVP+"

  const bw = player.stats.bedwars;
  console.log(bw?.wins); // raw, straight from the API
  console.log(bw?.computed.level); // fractional star
  console.log(bw?.computed.prestige.name); // prestige name
  console.log(bw?.computed.overall.finalsForNextFkdr); // finals to next whole FKDR
}

HypixelClient is an alias for HypixelApiService. The client is organised by subdomain: hypixel.player.*, hypixel.guild.*, hypixel.network.*, hypixel.resources.*, hypixel.skyblock.*, and hypixel.housing.*, plus top-level ping, request, hasApiKey, and clearCache. Pass an IGN or a UUID to any player-shaped method; the client resolves names to UUIDs for you. Methods return null rather than throwing when there is no API key, the target is unknown, or the upstream call fails.

Configuration

There is no .env file to wire up. Configuration is passed straight to the constructor, either as a bare key string, a static object, or a live source function that the client reads on every call (so a host can hot-apply key or TTL changes).

Option	Required	Default	Description
apiKey	yes	none	Your Hypixel API key as a string or string[]. Without it, endpoint methods return null
pingApiKey	no	""	Key(s) for the external ping provider as a string or string[]; only needed for ping()
cacheTtlSeconds	no	300	Cache lifetime in seconds. Sits above Hypixel's per-player cooldown

import { HypixelClient } from "@breezil/hypixel-api";

// 1. Bare key string
const a = new HypixelClient("YOUR-API-KEY");

// 2. Static config object
const b = new HypixelClient({
  apiKey: "YOUR-API-KEY",
  pingApiKey: "PING-PROVIDER-KEY",
  cacheTtlSeconds: 300,
});

// 3. Live config source, read per call, so key/TTL edits hot-apply
const c = new HypixelClient(() => ({
  apiKey: currentApiKey,
  pingApiKey: currentPingKey,
  cacheTtlSeconds: 300,
}));

// 4. Multi-key: round-robin with per-key rate-limit tracking
const d = new HypixelClient({
  apiKey: ["KEY1", "KEY2", "KEY3"],
  pingApiKey: ["PING-KEY1", "PING-KEY2"],
});

When you pass an array, requests round-robin across the keys. Each key gets its own rate-limit budget tracked independently from response headers. When one key is exhausted (HTTP 429), the pipeline automatically rotates to the next key on the next retry attempt, so a pool of N keys sustains roughly N times the single-key throughput. Per-player cooldowns always return null immediately regardless of how many keys are configured, because the cooldown is player-scoped, not key-scoped. Inspect per-key budget state with client.keys().

Injected identity layer

The second constructor argument injects the uuid/name resolver. Omit it for the built-in Mojang resolver (bidirectional lookups, single-flight, negative caching, in-memory LRU). Persistence is pluggable through the IdentityStore port: keep the default memory store, point a JsonFileIdentityStore at a file, or implement the port over your own database. See Resolver & Identity Stores for the full contract.

import {
  HypixelClient,
  createResolver,
  mojangProvider,
  JsonFileIdentityStore,
} from "@breezil/hypixel-api";

const resolver = createResolver({
  providers: [mojangProvider()],
  store: new JsonFileIdentityStore("./identity-cache.json"),
});

const hypixel = new HypixelClient("YOUR-API-KEY", resolver);

Where next

• API Overview for the endpoint-to-method map
• Client & Config for the pipeline behavior (cache, rate limit, retries)
• Computed Layer for every derived value and its formula