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

Feature	Default	Description
oauth	yes	OAuth2 authorization code flow with PKCE, for acting on behalf of other users.

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.