Usage

Reading the official Lichess API documentation before working with this library is recommended. Response schemata are not available here as they are already present at the aforementioned URL.

Client

class lichess.Client(token: str = '', *, session: Session | None = None)

A class that represents a client.

Parameters:

token (Optional[str]) – The Lichess API token.

Note

Providing an invalid token will only expose public endpoints.

Parameters:

session (Optional[requests.Session]) – The session to use.

@on_new_game_state(game_id: str)

Event that is called when there is a new game state.

Note

The first response is always of type gameFull.

Parameters:

game_id (str) – The ID of the game.

@on_game_status_change(user_ids: Set[str], *, with_current_games: bool | None = None)

Event that is called when a game starts or finishes among the pool of users.

Parameters:

  • user_ids (Set[str]) – The pool of users.

  • with_current_games (Optional[bool]) – Whether to include the already started games, or not.

@on_new_event

Event that is called when there is a new incoming event.

Note

When the stream opens, all current challenges and games are sent.

@on_new_game_state(game_id: str)

Event that is called when there is a new game state.

Note

The first response is always of type gameFull.

Parameters:

game_id (str) – The ID of the game.

@on_new_tv_game

Event that is called when a new game is displayed on TV.

abort_game(game_id: str) → bool

Aborts an ongoing game.

Parameters:

game_id (str) – The ID of the game.

accept_challenge(challenge_id: str) → bool

Accepts an incoming challenge.

Parameters:

challenge_id (str) – The ID of the challenge.

accept_join_request(team_id: str, user_id: str) → bool

Accepts a user’s join request for a team.

Parameters:

  • team_id (str) – The ID of the team.

  • user_id (str) – The ID of the user.

add_games_to_stream(game_ids: List[str], stream_id: str) → None

Adds games to an existing stream.

Parameters:

  • game_ids (List[str]) – The list of game IDs.

  • stream_id (str) – Whether to include the already started games, or not.

add_time_to_clock(game_id: str, time: Range[1, 86400]) → bool

Adds extra time to the opponent’s clock.

Parameters:

  • game_id (str) – The game ID.

  • time (Range[1, 86400]) – The number of seconds to add.

berserk_game(game_id: str) → bool

Berserks a tournament game, which halves the clock time, grants an extra point upon winning.

Note

This feature is only available in arena tournaments that allow berserks, and before each player has made a move.

Parameters:

game_id (str) – The ID of the game.

cancel_challenge(challenge_id: str, *, opponent_token: str | None = None) → bool

Cancels an incoming challenge.

Parameters:

  • challenge_id (str) – The ID of the challenge.

  • opponent_token (Optional[str]) – The opponents API token with the challenge:write scope enabled.

Note

If provided, the game can be cancelled even if both players have made a move.

challenge_ai(*, level: Range[1, 8] = None, rated: bool | None = None, time: Range[0, 10800] | None = None, increment: Range[0, 60] | None = None, days: Literal[1, 2, 3, 5, 7, 10, 14] | None = None, color: Literal['random', 'white', 'black'] | None = None, variant: Literal['standard', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck', 'fromPosition'] | None = None, fen: str | None = None) → Game

Starts a game with the Lichess AI.

Note

Make sure to also have the incoming events stream open, to be notified when the game starts.

Parameters:

  • level (Optional[Range[1, 8]]) – The strength of the AI.

  • rated (Optional[bool]) – Whether the game is rated, and impacts player ratings, or casual.

  • time (Optional[Range[0, 10800]]) – The initial clock time, in seconds.

Note

If empty, a correspondence game is created.

Parameters:

increment (Optional[Range[0, 60]]) – The clock incremenet, in seconds.

Note

If empty, a correspondence game is created.

Parameters:

days (Optional[Literal[1, 2, 3, 5, 7, 10, 14]]) – The number of days per turn.

Note

This is required for correspondence seeks.

Parameters:

  • variant (Optional[Literal["ultraBullet" ,"bullet" ,"blitz" ,"rapid" ,"classical" ,"correspondence" ,"chess960" ,"crazyhouse" ,"antichess" ,"atomic" ,"horde" ,"kingOfTheHill" ,"racingKings" ,"threeCheck"]]) – The game variant.

  • color (Optional[Literal["random", "white", "black"]]) – The color to play with.

  • fen (Optional[str]) – The custom initial position using FEN.

Note

The variant must be “standard”, “fromPosition”, or “chess960”, and the game cannot be rated. Castling moves will use UCI_Chess960 notation.

claim_victory(game_id: str) → bool

Claim victory when the opponent has left an ongoing game.

Parameters:

game_id (str) – The ID of the game.

create_challenge(username: str, *, rated: bool | None = None, time: Range[0, 10800] | None = None, increment: Range[0, 180] | None = None, days: Literal[1, 2, 3, 5, 7, 10, 14] | None = None, color: Literal['random', 'white', 'black'] | None = None, variant: Literal['standard', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck', 'fromPosition'] | None = None, fen: str | None = None, keep_alive: bool | None = None, acceptance_token: str | None = None, message: str | None = None, rules: Literal['noAbort', 'noRematch', 'noGiveTime', 'noClaimWin'] | None = None) → None

Challenges a user to play.

Note

Make sure to also have the incoming events stream open, to be notified when the game starts.

Parameters:

  • username (str) – The username of the player.

  • rated (Optional[bool]) – Whether the game is rated, and impacts player ratings, or casual.

  • time (Optional[Range[0, 10800]]) – The initial clock time, in seconds.

Note

If empty, a correspondence game is created.

Parameters:

increment (Optional[Range[0, 180]]) – The clock incremenet, in seconds.

Note

If empty, a correspondence game is created.

Parameters:

days (Optional[Literal[1, 2, 3, 5, 7, 10, 14]]) – The number of days per turn.

Note

This is required for correspondence seeks.

Parameters:

  • variant (Optional[Literal["ultraBullet" ,"bullet" ,"blitz" ,"rapid" ,"classical" ,"correspondence" ,"chess960" ,"crazyhouse" ,"antichess" ,"atomic" ,"horde" ,"kingOfTheHill" ,"racingKings" ,"threeCheck"]]) – The game variant.

  • color (Optional[Literal["random", "white", "black"]]) – The color to play with.

  • fen (Optional[str]) – The custom initial position using FEN.

Note

The variant must be “standard”, “fromPosition”, or “chess960”, and the game cannot be rated. Castling moves will use UCI_Chess960 notation.

Parameters:

keep_alive (Optional[bool]) – Whether to keep the challenge alive infinitely or not.

Note

If set to False or if left empty, the response is not streamed, and the challenge expires after 20 seconds if not accepted by the opponent.

Parameters:

acceptance_token (Optional[bool]) – The token of the receiving user, which access to the challenge:write scope.

Note

Providing a valid token immediately accepts the challenge and starts the game.

Parameters:

message (Optional[str]) – The message that is sent to each player, when the game starts.

Parameters:

rules (Optional[Literal["noAbort", "noRematch", "noGiveTime", "noClaimWin"]]) – Extra games properties, restricting one’s capabilities during the game.

create_challenge_tokens(users: List[str], description: str) → bool

Creates and obtains challenge:write tokens for multiple users.

Note

If a similar token already exists for a user, it is reused.

Parameters:

  • users (List[str]) – The list of usernames of users.

  • description (str) – The description of the tokens.

create_open_challenge(*, rated: bool | None = None, time: Range[0, 10800] | None = None, increment: Range[0, 60] | None = None, days: Literal[1, 2, 3, 5, 7, 10, 14] | None = None, variant: Literal['standard', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck', 'fromPosition'] | None = None, fen: str | None = None, rules: Literal['noAbort', 'noRematch', 'noGiveTime', 'noClaimWin'] | None = None, users: Tuple[str, str] | None = None) → None

Creates an open-ended challenge that any two players can join.

Note

These challenges expire after 24 hours.

Parameters:

  • rated (Optional[bool]) – Whether the game is rated, and impacts player ratings, or casual.

  • time (Optional[Range[0, 10800]]) – The initial clock time, in seconds.

Note

If empty, a correspondence game is created.

Parameters:

increment (Optional[Range[0, 60]]) – The clock incremenet, in seconds.

Note

If empty, a correspondence game is created.

Parameters:

days (Optional[Literal[1, 2, 3, 5, 7, 10, 14]]) – The number of days per turn.

Note

This is required for correspondence seeks.

Parameters:

  • variant (Optional[Literal["ultraBullet" ,"bullet" ,"blitz" ,"rapid" ,"classical" ,"correspondence" ,"chess960" ,"crazyhouse" ,"antichess" ,"atomic" ,"horde" ,"kingOfTheHill" ,"racingKings" ,"threeCheck"]]) – The game variant.

  • fen (Optional[str]) – The custom initial position using FEN.

Note

The variant must be “standard”, “fromPosition”, or “chess960”, and the game cannot be rated. Castling moves will use UCI_Chess960 notation.

Parameters:

keep_alive (Optional[bool]) – Whether to keep the challenge alive infinitely or not.

Note

If set to False or if left empty, the response is not streamed, and the challenge expires after 20 seconds if not accepted by the opponent.

Parameters:

  • rules (Optional[Literal["noAbort", "noRematch", "noGiveTime", "noClaimWin"]]) – Extra games properties, restricting one’s capabilities during the game.

  • users (Optional[Tuple[str, str]]) – The usernames of a pair of users who will be playing the game.

Note

The first username gets the white pieces.

create_puzzle_race() → LichessObject

Creates a new private puzzle race.

..note

The user who creates the race must join the race page, and manually start the race when enough players have joined.
create_seek(*, rated: bool | None = None, time: Range[0, 180] | None = None, increment: Range[0, 180] | None = None, days: Literal[1, 2, 3, 5, 7, 10, 14] | None = None, variant: Literal['standard', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck', 'fromPosition'] | None = None, color: Literal['random', 'white', 'black'] | None = None, rating_range: Range | None = None) → Iterator[LichessObject]

Creates a public seek to start a game with a random player.

Note

Make sure to also have the incoming events stream open, to be notified when a game starts.

Parameters:

  • rated (Optional[bool]) – Whether the game is rated, and impacts player ratings, or casual.

  • time (Optional[Range[0, 180]]) – The initial clock time, in minutes.

Note

This is required for real-time seeks.

Parameters:

increment (Optional[Range[0, 180]]) – The clock incremenet, in seconds.

Note

This is required for real-time seeks.

Parameters:

days (Optional[Literal[1, 2, 3, 5, 7, 10, 14]]) – The number of days per turn.

Note

This is required for correspondence seeks.

Parameters:

  • variant (Optional[Literal["ultraBullet" ,"bullet" ,"blitz" ,"rapid" ,"classical" ,"correspondence" ,"chess960" ,"crazyhouse" ,"antichess" ,"atomic" ,"horde" ,"kingOfTheHill" ,"racingKings" ,"threeCheck"]]) – The game variant.

  • color (Optional[Literal["random", "white", "black"]]) – The color to play with.

  • rating_range (Optional[Range]) – The rating range of potential opponents.

decline_challenge(challenge_id: str, *, reason: Literal['generic', 'later', 'tooFast', 'tooSlow', 'timeControl', 'rated', 'casual', 'standard', 'variant', 'noBot', 'onlyBot'] | None = None) → bool

Declines an incoming challenge.

Parameters:

  • challenge_id (str) – The ID of the challenge.

  • reason (Optional[Literal["generic", "later", "tooFast", "tooSlow", "timeControl", "rated", "casual", "standard", "variant", "noBot", "onlyBot"]]) – The reason for the rejection.

decline_join_request(team_id: str, user_id: str) → bool

Declines a user’s join request for a team.

Parameters:

  • team_id (str) – The ID of the team.

  • user_id (str) – The ID of the user.

export_game(game_id: str, *, with_pgn_moves: bool | None = None, with_pgn: bool | None = None, with_pgn_tags: bool | None = None, with_clock_comments: bool | None = None, with_evaluation: bool | None = None, with_opening: bool | None = None, with_annotations: bool | None = None, players: str | None = None) → Game

Exports a game.

Note

Ongoing games have their last 3 moves omitted after move 5.

Parameters:

  • game_id (str) – The ID of the game.

  • with_pgn_moves (Optional[bool]) – Whether to include the PGN moves, or not.

  • with_pgn (Optional[bool]) – Whether to include the full PGN, or not.

  • with_pgn_tags (Optional[bool]) – Whether to include the PGN tags, or not.

  • with_clock_comments (Optional[bool]) – Whether to include clock comments, or not, when available.

  • with_evaluation (Optional[bool]) – Whether to include the analysis evaluation comments in the PGN, or not, when available.

  • with_opening (Optional[bool]) – Whether to include the opening name, or not.

  • with_annotations (Optional[bool]) – Whether to insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination, or not.

  • players (Optional[str]) – URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. =

export_games(game_ids: List[str], *, with_pgn_moves: bool | None = None, with_pgn: bool | None = None, with_pgn_tags: bool | None = None, with_clock_comments: bool | None = None, with_evaluation: bool | None = None, with_opening: bool | None = None, with_annotations: bool | None = None, players: str | None = None) → List[Game]

Exports up to 300 games by their IDs.

Note

Games are sorted in reverse chronological order (most recent first).

Note

Ongoing games have their last 3 moves omitted after move 5.

Parameters:

  • game_ids (List[str]) – A list of game IDs.

  • with_pgn_moves (Optional[bool]) – Whether to include the PGN moves, or not.

  • with_pgn (Optional[bool]) – Whether to include the full PGN, or not.

  • with_pgn_tags (Optional[bool]) – Whether to include the PGN tags, or not.

  • with_clock_comments (Optional[bool]) – Whether to include clock comments, or not, when available.

  • with_evaluation (Optional[bool]) – Whether to include the analysis evaluation comments in the PGN, or not, when available.

  • with_opening (Optional[bool]) – Whether to include the opening name, or not.

  • with_annotations (Optional[bool]) – Whether to insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination, or not.

  • players (Optional[str]) – URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. =

export_latest_game(username: str, *, with_pgn_moves: bool | None = None, with_pgn: bool | None = None, with_pgn_tags: bool | None = None, with_clock_comments: bool | None = None, with_evaluation: bool | None = None, with_opening: bool | None = None, with_annotations: bool | None = None, players: str | None = None) → Game

Exports the ongoing game, or the last game played, of a user.

Note

If the game is ongoing, the last 3 moves are omitted.

Parameters:

  • username (str) – The username of the user.

  • with_pgn_moves (Optional[bool]) – Whether to include the PGN moves, or not.

  • with_pgn (Optional[bool]) – Whether to include the full PGN, or not.

  • with_pgn_tags (Optional[bool]) – Whether to include the PGN tags, or not.

  • with_clock_comments (Optional[bool]) – Whether to include clock comments, or not, when available.

  • with_evaluation (Optional[bool]) – Whether to include the analysis evaluation comments in the PGN, or not, when available.

  • with_opening (Optional[bool]) – Whether to include the opening name, or not.

  • with_annotations (Optional[bool]) – Whether to insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination, or not.

  • players (Optional[str]) – URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. =

export_user_games(username: str, *, since: datetime | None = None, until: datetime | None = None, limit: int | None = None, opponent: str | None = None, rated: bool | None = None, performances: List[Literal['ultraBullet', 'bullet', 'blitz', 'rapid', 'classical', 'correspondence', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck']] | None = None, color: Literal['white', 'black'] | None = None, analysed: bool | None = None, with_pgn_moves: bool | None = None, with_pgn: bool | None = None, with_pgn_tags: bool | None = None, with_clock_comments: bool | None = None, with_evaluation: bool | None = None, with_opening: bool | None = None, with_ongoing: bool | None = None, with_finished: bool | None = None, with_annotations: bool | None = None, players: str | None = None, reverse: bool | None = None) → Iterator[Game]

Exports all games of a user.

Note

Games are sorted in reverse chronological order (most recent first).

Parameters:

  • username (str) – The username of the user.

  • since (Optional[datetime]) – Games played since this timestamp.

  • until (Optional[datetime]) – Games played until this timestamp.

  • limit (Optional[int]) – The maximum number of games to include.

  • opponent (Optional[str]) – The username of the opponent.

  • rated (Optional[bool]) – Whether to only include rated games, or not.

  • performances (Optional[List[Literal["ultraBullet" ,"bullet" ,"blitz" ,"rapid" ,"classical" ,"correspondence" ,"chess960" ,"crazyhouse" ,"antichess" ,"atomic" ,"horde" ,"kingOfTheHill" ,"racingKings" ,"threeCheck"]]]) – The speed or variant of the game.

  • color (Optional[Literal["white", "black"]]) – The color played by the user.

  • analysed (Optional[bool]) – Whether to only include games with a computer analysis available, or not.

  • with_pgn_moves (Optional[bool]) – Whether to include the PGN moves, or not.

  • with_pgn (Optional[bool]) – Whether to include the full PGN, or not.

  • with_pgn_tags (Optional[bool]) – Whether to include the PGN tags, or not.

  • with_clock_comments (Optional[bool]) – Whether to include clock comments, or not, when available.

  • with_evaluation (Optional[bool]) – Whether to include the analysis evaluation comments in the PGN, or not, when available.

  • with_opening (Optional[bool]) – Whether to include the opening name, or not.

  • ongoing (Optional[bool]) – Whether to include ongoing games, or not.

  • finished (Optional[bool]) – Whether to include finished games, or not.

  • with_annotations (Optional[bool]) – Whether to insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination, or not.

  • players (Optional[str]) – URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. =

  • reverse (Optional[bool]) – Whether to reverse the order of games, or not.

follow(username: str) → None

Follows a player, adding them to the logged in user’s list of Lichess friends.

Parameters:

username (str) – The username of the user.

get_arena_tournaments(team_id: str, *, limit: int | None = None) → Iterator[ArenaTournament]

Gets all the Arena tournaments of a team.

Note

Tournaments are sorted in reverse chronological order (most recent first).

Parameters:

  • team_id (str) – The ID of the team.

  • limit (Optional[int]) – The maximum number of tournaments to fetch.

get_challenges() → LichessObject

Gets a list of challenges created by or target at the logged in user.

get_crosstable(user_1: str, user_2: str, *, with_current_match_data: bool | None = None) → LichessObject

Gets the total number of games, and current score, of any two users.

Parameters:

  • user_1 (str) – The first user.

  • user_2 (str) – The second user.

  • with_current_match_data (bool) – Whether to get the current match data, or not, if any.

get_daily_puzzle() → Iterator[LichessObject]

Gets the daily puzzle.

get_email_address() → str

Gets the email address of the logged in user.

get_followed_players() → Iterator[Player]

Gets users followed by the logged in user.

get_game_chat(game_id: str) → List[LichessObject]

Fetches a game’s chat history.

Parameters:

game_id (str) – The ID of the game.

get_join_requests(team_id: str) → RequestList

Gets pending join requests of a team.

Parameters:

team_id (str) – The ID of the team.

get_kid_mode_status() → bool

Gets the kid mode status of the logged in user.

get_leaderboard(number: Range[1, 200], performance: Literal['ultraBullet', 'bullet', 'blitz', 'rapid', 'classical', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck']) → LichessObject

Gets the leaderboard for a single speed or variant.

Note

There is no leaderboard for correspondence or puzzles.

Parameters:

  • number (Range[1, 200]) – The number of users to fetch.

  • performance (Literal["ultraBullet", "bullet", "blitz", "rapid", "classical", "chess960", "crazyhouse", "antichess", "atomic", "horde", "kingOfTheHill", "racingKings", "threeCheck"]) – The speed or variant.

get_live_streamers() → List[LichessObject]

Gets basic info about currently streaming users.

get_ongoing_games(*, limit: Range[1, 50] | None = None) → List[LichessObject]

Gets ongoing games of the logged in user.

Note

The most urgent games are listed first.

Parameters:

limit – The maximum number of games to fetch.

get_online_bots() → Iterator[Player]

Fetches a list of online bots.

get_performance_statistic(username: str, performance: Literal['ultraBullet', 'bullet', 'blitz', 'rapid', 'classical', 'correspondence', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck']) → PerformanceStatistic

Gets the performance statistic of a user, for a single performance.

Parameters:

  • username (str) – The username of the user.

  • performance (Literal["ultraBullet", "bullet", "blitz", "rapid", "classical", "correspondence", "chess960", "crazyhouse", "antichess", "atomic", "horde", "kingOfTheHill", "racingKings", "threeCheck"]) – The speed or variant.

Gets popular teams.

Parameters:

page (Optional[int]) – The page number.

get_preferences() → LichessObject

Gets the preferences of the logged in user.

get_profile() → Player

Gets public information about the logged in user.

get_puzzle(puzzle_id: str) → Iterator[LichessObject]

Gets a puzzle using its ID.

Parameters:

puzzle_id (str) – The ID of the puzzle.

get_puzzle_activity(*, limit: int | None = None) → Iterator[Puzzle]

Gets the puzzle activity of the logged in user.

Parameters:

limit (Optional[int]) – The maximum number of puzzles to fetch.

get_puzzle_dashboard(days: int) → LichessObject

Gets the puzzle dashboard of the logged in user.

Parameters:

days (int) – The number of days to look back when aggregating puzzle results.

get_rating_history(username: str) → RatingHistory

Gets the rating history of a user, for all speeds and variants.

Parameters:

username (str) – The username of the user.

get_storm_dashboard(username: str, *, days: Range[0, 365] | None) → LichessObject

Gets the storm dashboard of a user.

Parameters:

  • username (str) – The username of the user.

  • days (Optional[Range[0, 365]]) – The number of days of history to return.

Note

Set days to 0 if you only care about high scores.

get_swiss_tournaments(team_id: str, *, limit: int | None = None) → Iterator[SwissTournament]

Gets all the Swiss tournaments of a team.

Note

Tournaments are sorted in reverse chronological order (most recent first).

Parameters:

  • team_id (str) – The ID of the team.

  • limit (Optional[int]) – The maximum number of tournaments to fetch.

get_team(team_id: str) → LichessObject

Gets information about a single team.

Parameters:

team_id (str) – The ID of the team.

get_team_members(team_id: str) → Iterator[LichessObject | Player]

Gets members of a team.

Note

Members are sorted in reverse chronological order of joining the team (most recent first).

Parameters:

team_id (str) – The ID of the team.

get_top_10() → LichessObject

Gets the top 10 players for each speed and variant.

get_tv_channel_games(channel: str, *, number: Range[1, 30] | None = None, with_pgn_moves: bool | None = None, with_pgn: bool | None = None, with_pgn_tags: bool | None = None, with_clock_comments: bool | None = None, with_opening: bool | None = None) → Iterator[Game]

Gets a list of ongoing TV games for a given channel.

Parameters:

  • channel (str) – The name of the channel in camel case.

  • number (Optional[Range[1, 30]]) – The number of games to fetch.

  • with_pgn_moves (Optional[bool]) – Whether to include the PGN moves, or not.

  • with_pgn (Optional[bool]) – Whether to include the full PGN, or not.

  • with_pgn_tags (Optional[bool]) – Whether to include the PGN tags, or not.

  • with_clock_comments (Optional[bool]) – Whether to include clock comments, or not, when available.

  • with_opening (Optional[bool]) – Whether to include the opening name, or not.

get_tv_games() → TvGamesList

Gets current TV games.

get_user(username: str, *, with_trophies: bool | None = None) → Player

Gets the leaderboard for a single speed or variant.

Note

There is no leaderboard for correspondence or puzzles.

Parameters:

  • username (str) – The username of the user.

  • with_trophies (Optional[bool]) – Whether to include user trophies, or not.

get_user_statuses(user_ids: List[str], *, with_game_ids: bool | None = None) → LichessObject

Gets the statuses of given users.

Parameters:

  • user_ids (List[str]) – The list of user IDs.

  • with_game_ids (Optional[bool]) – Whether to return the ID of the game being played, or not.

get_user_teams(username: str) → List[LichessObject]

Gets a user’s teams.

Parameters:

username (str) – The user’s username.

get_users(user_ids: List[str]) → List[Player]

Gets up to 300 users by their IDs.

Note

Users are returned in the same order as the IDs.

Parameters:

user_ids (List[str]) – The list of user IDs.

handle_draw_offer(game_id: str, accept: bool) → bool

Handles (or creates) a draw offer from an ongoing game.

Parameters:

  • game_id (str) – The ID of the game.

  • accept (bool) – Whether to accept (or to create) the draw offer or not.

handle_takeback_offer(game_id: str, accept: bool) → bool

Handles (or creates) a takeback offer from an ongoing game.

Parameters:

  • game_id (str) – The ID of the game.

  • accept (bool) – Whether to accept (or to create) the takeback or not.

import_game(pgn: str) → LichessObject

Imports a game using its PGN.

Parameters:

pgn (str) – The PGN.

join_team(team_id: str, *, message: str | None = None, password: str | None = None) → None

Joins a team.

Parameters:

  • team_id (str) – The ID of the team.

  • message (Optional[str]) – The request message, if the team requires one.

  • password (Optional[str]) – The password, if the team requires one.

kick_team_member(team_id: str, user_id: str) → bool

Kicks a user from a team.

Parameters:

  • team_id (str) – The ID of the team.

  • user_id (str) – The ID of the user.

leave_team(team_id: str) → None

Leaves a team.

Parameters:

team_id (str) – The ID of the team.

make_board_move(game_id: str, move: str, *, with_draw_offering: bool | None = None) → bool

Makes a move in a game being played.

Parameters:

  • game_id (str) – The ID of the game.

  • move (str) – The move to play, in the UCI format.

  • with_draw_offering (Optional[bool]) – Whether to offer (or agree to) a draw or not.

message_team_members(team_id: str, message: str | None = None) → bool

Messages all members of a team.

Parameters:

  • team_id (str) – The ID of the team.

  • message (Optional[str]) – The message to post.

post_chat_message(game_id: str, room: Literal['player', 'spectator'], text: str) → bool

Posts a message to the player or spectator chat, in a game being played.

Parameters:

  • game_id (str) – The ID of the game.

  • room (Literal["player", "spectator"]) – The room to post the message in.

  • text (str) – The contents of the message to post.

resign_game(game_id: str) → bool

Resigns an ongoing game.

Parameters:

game_id (str) – The ID of the game.

search_team(*, text: str | None = None, page: int | None = None) → LichessObject

Searches for teams.

Parameters:

  • text (Optional[str]) – The query text.

  • page (Optional[int]) – The page number.

set_kid_mode_status(value: bool) → bool

Sets the kid mode status of the logged in user.

start_game_clocks(game_id: str, *, token_1: str | None = None, token_2: str | None = None) → bool

Starts the clocks of a game immediately, even if a player has not made a move.

Note

If the clocks have already started, this call will have no effect.

Parameters:

  • game_id (str) – The game ID.

  • token_1 (Optional[str]) – The token of one player.

  • token_2 (Optional[str]) – The token of the other player.

Note

Both tokens need to have the challenge:write scope enabled.

stream_board_state(game_id: str) → Iterator[Game | LichessObject]

Streams changes in the state of a game being played.

Parameters:

game_id (str) – The ID of the game.

stream_game_moves(game_id: str) → List[Game | LichessObject]

Emits an event when a move is made.

Note

After move 5, the stream intentionally remains 3 moves behind the game status, to prevent cheat bots from using this API.

Note

No more than 8 game streams can be opened at the same time from the same IP address.

Parameters:

game_id (str) – The game ID.

stream_games(game_ids: List[str], stream_id: str) → Iterator[Game]

First outputs the games that already exists, then emits an event each time a game is started or finished.

Parameters:

  • game_ids (List[str]) – The list of game IDs.

  • stream_id (str) – Arbitrary stream ID that you can later use to add game IDs to the stream.

stream_games_among_users(user_ids: Set[str], *, with_current_games: bool | None = None) → Iterator[Game]

Emits an event when a game starts or finishes among the pool of users.

Parameters:

  • user_ids (Set[str]) – The pool of users’ IDs.

  • with_current_games (Optional[bool]) – Whether to include the already started games, or not.

stream_incoming_events() → Iterator[LichessObject]

Streams the logged in user’s incoming events.

Note

When the stream opens, all current challenges and games are sent.

stream_tv_game() → Iterator[LichessObject]

Streams the current TV game.

unfollow(username: str) → None

Unfollows a player, removing them to the logged in user’s list of Lichess friends.

Parameters:

username (str) – The username of the user.

upgrade_to_bot_account() → bool

Upgrades the account of the logged in user to a Bot account.

Note

The account cannot have played any game before becoming a Bot account.

Bot

Note

All methods of this class are overrides of corresponding methods in Client.

class lichess.Bot(token: str | None = '', *, session: Session | None = None)

A class that represents a Bot account.

@on_new_game_state(game_id: str)

Event that is called when there is a new game state.

Note

The first response is always of type gameFull.

Parameters:

game_id (str) – The ID of the game.

abort_game(game_id: str) → bool

Aborts an ongoing game.

Parameters:

game_id (str) – The ID of the game.

get_game_chat(game_id: str) → List[LichessObject]

Fetches a game’s chat history.

Parameters:

game_id (str) – The ID of the game.

make_board_move(game_id: str, move: str, *, with_draw_offering: bool | None = None) → bool

Makes a move in a game being played.

Parameters:

  • game_id (str) – The ID of the game.

  • move (str) – The move to play, in the UCI format.

  • with_draw_offering (Optional[bool]) – Whether to offer (or agree to) a draw or not.

post_chat_message(game_id: str, room: Literal['player', 'spectator'], text: str) → bool

Posts a message to the player or spectator chat, in a game being played.

Parameters:

  • game_id (str) – The ID of the game.

  • room (Literal["player", "spectator"]) – The room to post the message in.

  • text (str) – The contents of the message to post.

resign_game(game_id: str) → bool

Resigns an ongoing game.

Parameters:

game_id (str) – The ID of the game.

stream_board_state(game_id: str) → Iterator[Game | LichessObject]

Streams changes in the state of a game being played.

Parameters:

game_id (str) – The ID of the game.