Skip to content

About

Typed Rust + Python SDK for the Hypixel Public API, async core, SkyBlock helpers (bazaar, auctions, networth, NBT decoding)

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

hypixel-sdk

crates.io docs.rs PyPI CI License: MIT

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_all fetches 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 extra catch-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_summary resolves 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.

Layout

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

Authentication

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.

Rust

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 key

Python

The native module targets the active CPython interpreter. Set up a virtualenv and build the extension into it with maturin.

Setup

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.toml

Bash / 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.toml

You 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, then maturin develop --uv -m crates/hypixel-py/Cargo.toml.

Usage

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).

Examples

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 Feromond

Development

A justfile wraps the common tasks:

just check        # fmt-check + clippy + cargo test
just py-build     # maturin develop
just py-test      # build then pytest

Tests

  • Rust unit + integration tests run fully offline against wiremock and the fixtures in crates/hypixel/tests/fixtures.
  • Python tests run against a local mock HTTP server (no key required).
  • Live checks are opt-in: set HYPIXEL_API_KEY and hit a real endpoint from an example.

Updating the API spec

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.

License

MIT

About

Typed Rust + Python SDK for the Hypixel Public API, async core, SkyBlock helpers (bazaar, auctions, networth, NBT decoding)

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages