A typed SDK for the Hypixel Public API, written in Rust with a focus on SkyBlock, and published to Python via PyO3 + maturin.
- Endpoint coverage for the v2 API: general, SkyBlock, and resource endpoints.
skyblock_auctions_allfetches the whole auction listing concurrently. - Async Rust core (
reqwest/tokio) usable on its own, plus sync and async Python clients. Rate-limit retries and response caching can be turned on when building a client. - Typed models, including the deep SkyBlock member sections (skills,
dungeons, slayers, pets, currencies, HOTM). Every model keeps unknown fields
in an
extracatch-all so responses keep parsing as Hypixel changes things. - Leveling math for the SkyBlock curves: skills, catacombs and dungeon
classes, slayers, pets, Heart of the Mountain, and the profile level.
member_summaryresolves all of them for a member in one call. - Market and networth tools: bazaar spreads, after-tax flip finding, lowest-BIN aggregation (by name or by decoded item id), and networth estimates that count recombobulators, potato books, and enchantments.
- NBT decoding for the base64+gzip item blobs, and Mojang helpers to turn usernames into UUIDs and back.
crates/hypixel core async Rust SDK (crate `hypixel-sdk`, imported as `hypixel`)
crates/hypixel-py PyO3 bindings (PyPI `hypixel-sdk`, imported as `hypixel`)
spec/openapi.json vendored Hypixel OpenAPI spec used to track API coverage
Keyed endpoints need an API key from the
Developer Dashboard. The keyless endpoints (all
resource_*, plus the SkyBlock auctions, auctions_ended, bazaar,
firesales, and news endpoints) work without one.
let client = hypixel::HypixelClient::new("YOUR-API-KEY");
let bazaar = client.skyblock_bazaar().await?;
println!("{} products", bazaar.products.len());cargo test --workspace # offline tests (wiremock + fixtures)
cargo run -p hypixel-sdk --example bazaar # needs no keyThe native module targets the active CPython interpreter. Set up a virtualenv and build the extension into it with maturin.
PowerShell (Windows):
python -m venv .venv
.\.venv\Scripts\Activate.ps1 # if blocked: Set-ExecutionPolicy -Scope Process -Bypass
pip install maturin pytest pytest-asyncio
maturin develop -m crates\hypixel-py\Cargo.tomlBash / Unix (or Git Bash on Windows):
python -m venv .venv
source .venv/bin/activate # Git Bash on Windows: source .venv/Scripts/activate
pip install maturin pytest pytest-asyncio
maturin develop -m crates/hypixel-py/Cargo.tomlYou can also skip activation and call the venv interpreter directly, e.g.
.\.venv\Scripts\python.exe examples\python\bazaar.py.
uv works too:
uv venv && uv pip install maturin pytest pytest-asyncio, thenmaturin develop --uv -m crates/hypixel-py/Cargo.toml.
from hypixel import Client
client = Client("YOUR-API-KEY")
print(len(client.skyblock_bazaar()["products"]), "products")import asyncio
from hypixel import AsyncClient
async def main():
client = AsyncClient() # keyless
page = await client.skyblock_auctions(0)
print(page["totalAuctions"], "auctions")
asyncio.run(main())Responses are returned as native Python objects (dicts/lists). Errors raise a
HypixelError subclass (MissingApiKeyError, InvalidApiKeyError,
RateLimitedError, ApiError, HttpError, DecodeError). Both clients accept
retry_on_rate_limit= and cache_ttl= keyword arguments, and module-level
mojang_uuid / mojang_username helpers (plus _async variants) resolve
usernames to UUIDs.
The hypixel.util submodule mirrors the Rust helpers: NBT decoding
(decode_nbt, decode_inventory, extract_item_stacks[_detailed]), leveling
math (skill_level, catacombs_level, slayer_level, pet_level,
hotm_tier, skyblock_level, and member_summary for a whole member at
once), market analysis (bazaar_spreads, bazaar_flips, lowest_bin,
lowest_bin_by_id), and networth valuation (price_book, value_items,
value_items_detailed).
Parallel Rust and Python examples live in examples/:
bazaar spreads, auction lowest-BIN, static resources, player lookup, a deep
SkyBlock profile read (skills/currencies/dungeons/slayers), and inventory
networth. For example:
cargo run -p hypixel-sdk --example bazaar # keyless
python examples/python/skyblock_profile.py # needs HYPIXEL_API_KEY; defaults to FeromondA justfile wraps the common tasks:
just check # fmt-check + clippy + cargo test
just py-build # maturin develop
just py-test # build then pytest- Rust unit + integration tests run fully offline against
wiremockand the fixtures incrates/hypixel/tests/fixtures. - Python tests run against a local mock HTTP server (no key required).
- Live checks are opt-in: set
HYPIXEL_API_KEYand hit a real endpoint from an example.
The vendored spec/openapi.json is extracted from the docs page at
https://api.hypixel.net. When Hypixel ships changes, re-extract it and diff against
the models.
MIT