lichess-api

An asynchronous client library for the current lichess.org API with all endpoints supported.

Quick start

Add the dependencies:

[dependencies]
lichess-api = "1.0"
tokio = { version = "1", features = ["full"] }

Example request:

use lichess_api::client::LichessApi;

#[tokio::main]
async fn main() -> lichess_api::error::Result<()> {
    let client = reqwest::Client::new();
    let token = std::env::var("LICHESS_TOKEN").ok();
    let api = LichessApi::new(client, token);

    let profile = api.get_profile().await?;
    println!("username: {}", profile.user.username);

    Ok(())
}

Authentication

Most endpoints require a bearer token but some don't. E.g. the daily puzzle, etc.

• Acting as yourself: generate a personal API token and pass it to LichessApi::new as above.
• Acting on behalf of another user: Ensure the oauth feature is enabled and use the OAuth2 authorization code flow with PKCE, via AuthorizationUrl and PendingAuthorization.

Features

CLI

cargo install --path cli
lichess users get thibault
lichess --api-token "$LICHESS_TOKEN" challenges create <username> --rated
lichess --json puzzles daily

• --api-token / -a: for endpoints that require authentication.
• --json: pretty-printed JSON instead of Rust debug format.
• --verbose / -v: enable debug logging.

Run lichess --help or lichess <category> --help for the full list of categories and commands.

Contributing

If you have any ideas, bug reports, feature requests, or fixes, please make an issue or submit a pull request.

Thanks.