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 thechallenge: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 thechallenge: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.
- get_popular_teams(*, page: int | None = None) LichessObject
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
to0
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.