halo_api

Unofficial Halo Infinite REST API client for Rust: CSR/rank lookups, service records, match history, and more.

[!IMPORTANT] This is an unofficial, community-maintained library. It is not affiliated with, endorsed by Microsoft.

What this crate does

Separates authentication (HaloAuthClient) from Halo API operations (HaloInfiniteClient).
Acquires and caches both the Spartan token and Waypoint flight clearance.
Covers stats, skill, profile, UGC, progression, career rank, reward tracks, ban, and privacy endpoints.
Filters service records by season, playlist, mode, and ranked/social via ServiceRecordFilter.
Paces requests per Halo Waypoint origin (default 5/s) so bursts don't trip throttling; configure via HaloInfiniteClient::builder().
Automatically invalidates and retries once on an expired/unauthorized (401) response, instead of surfacing a hard failure the caller has to handle manually.

This crate depends on the xbox crate for Xbox Live authentication (XSTS tickets and XUID resolution). [HaloAuthClient] acquires and refreshes all Halo Waypoint credentials.

If your application already obtains Halo Waypoint credentials, use HaloAuthClient::from_tokens(spartan_token, clearance_token) instead. Those values remain private to the client, but the caller is responsible for replacing the client when they expire.

Quick start

use std::sync::Arc;

use halo_api::clients::hi::models::PlaylistId;
use halo_api::auth::HaloAuthClient;
use halo_api::clients::hi::{HaloInfiniteClient, Player};
use xbox::auth::LegacyPasswordProvider;
use xbox::XboxClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let xbox_client = Arc::new(XboxClient::new(LegacyPasswordProvider::new(
        "my-username",
        "my-password",
    )));
    let auth = HaloAuthClient::from_xbox_client(xbox_client.clone());
    let halo = HaloInfiniteClient::new(auth);

    let xuid = xbox_client.gamertag_to_xuid("Some Gamertag").await?;
    let csr = halo
        .playlist_csr(PlaylistId::RANKED_ARENA, &Player::from(&xuid))
        .await?;

    println!("{csr:?}");
    Ok(())
}

MSRV

This crate has a Minimum Supported Rust Version (MSRV) of 1.96.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option

Contribution

See CONTRIBUTING.md.