lichess-bot-runner

A small Python library for running a lichess.org bot. It streams incoming events, accepts challenges that match your criteria, plays games via a move function you provide, and challenges other online bots when idle so your bot keeps playing.

Features

• Accepts/declines challenges based on allowed variants and speeds
• Plays games by calling your make_move(board) function (python-chess board in, move out)
• Automatically challenges random online bots when not currently playing
• Runs matchmaking and game streaming concurrently in background threads

Install

pip install git+https://github.com/JakesMD/lichess-bot-runner.git

Usage

import chess
import chess.engine
from lichess_bot_runner import LichessBot

with chess.engine.SimpleEngine.popen_uci("stockfish") as engine:

    def make_move(board: chess.Board) -> chess.Move:
        result = engine.play(board, chess.engine.Limit(time=1.0))
        return result.move

    bot = LichessBot(token="your-lichess-bot-api-token", make_move=make_move)
    bot.run()

Your Lichess account must be upgraded to a bot account before it can use the bot API.

Your API token must have the bot:play and challenge:write scopes.

Configuration

LichessBot accepts the following arguments:

Argument	Default	Description
token	required	Lichess bot API token
make_move	required	Function that takes a chess.Board and returns a chess.Move
accepted_variants	{"standard"}	Variant keys to accept challenges for. Options: standard, chess960, crazyhouse, antichess, atomic, horde, kingOfTheHill, racingKings, threeCheck, fromPosition
accepted_speeds	{"bullet", "blitz", "rapid", "classical"}	Game speeds to accept challenges for. Options: ultraBullet, bullet, blitz, rapid, classical (correspondence unsupported — bots can't play correspondence games)
matchmaking_interval	3	Seconds between matchmaking checks
matchmaking_clock_limit	300	Clock limit in seconds for bots the matchmaker challenges
matchmaking_clock_increment	3	Clock increment in seconds for bots the matchmaker challenges
pending_challenge_timeout	15	Seconds to wait for a matchmaking challenge to be answered before challenging again