Chariot is a Java client for the Lichess API.
Lichess is a charity and entirely free/libre open source software.
Client.basic()
import chariot.Client;
var client = Client.basic()
client.withToken()
client.withPkce()
client.analysis().cloudEval()
client.bot().botsOnline()
client.broadcasts().official()
client.broadcasts().search()
client.broadcasts().exportPgn()
client.broadcasts().exportOneRoundPgn()
client.broadcasts().streamBroadcast()
client.broadcasts().broadcastById()
client.broadcasts().leaderboardById()
client.broadcasts().roundById()
client.broadcasts().byUserId()
client.broadcasts().topActive()
client.broadcasts().topUpcoming()
client.broadcasts().topPast()
client.broadcasts().playersById()
client.broadcasts().playerDetailsById()
client.challenges().challengeOpenEnded()
client.externalEngine().acquire()
client.externalEngine().answer()
client.externalEngine().analyse()
client.fide().playerById()
client.fide().searchFidePlayers()
client.games().byGameId()
client.games().byGameIds()
client.games().byUserId()
client.games().currentByUserId()
client.games().moveInfosByGameId()
client.games().gameInfosByUserIds()
client.games().addGameIdsToStream()
client.games().tvFeed()
client.games().tvChannels()
client.games().byChannel()
client.games().importGame()
client.openingExplorer().masters()
client.openingExplorer().lichess()
client.openingExplorer().player()
client.puzzles().dailyPuzzle()
client.puzzles().nextPuzzle()
client.puzzles().byId()
client.puzzles().stormDashboard()
client.puzzles().raceResult()
client.puzzles().batch()
client.puzzles().batchSolve()
client.simuls().simuls()
client.studies().exportStudiesByUserId()
client.studies().exportChaptersByStudyId()
client.studies().exportChapterByStudyAndChapterId()
client.studies().lastModifiedByStudyId()
client.studies().byPage()
client.studies().listStudies()
client.studies().listStudiesByUser()
client.tablebase().standard()
client.tablebase().atomic()
client.tablebase().antichess()
client.teams().numberOfTeams()
client.teams().search()
client.teams().searchByPage()
client.teams().popularTeams()
client.teams().byTeamId()
client.teams().byUserId()
client.teams().usersByTeamId()
client.teams().arenaByTeamId()
client.teams().swissByTeamId()
client.tournaments().currentTournaments()
client.tournaments().arenasCreatedByUserId()
client.tournaments().arenasPlayedByUserId()
client.tournaments().arenaById()
client.tournaments().swissById()
client.tournaments().gamesByArenaId()
client.tournaments().gamesBySwissId()
client.tournaments().resultsByArenaId()
client.tournaments().resultsBySwissId()
client.tournaments().swissTRF()
client.tournaments().teamBattleResultsById()
client.users().byId()
client.users().byIds()
client.users().top10()
client.users().leaderboard()
client.users().liveStreamers()
client.users().activityById()
client.users().statusById()
client.users().statusByIds()
client.users().ratingHistoryById()
client.users().crosstable()
client.users().performanceStatisticsByIdAndType()
client.users().autocompleteNames()
client.users().autocompleteUsers()Client.auth()
import chariot.Client;
var client = Client.auth()
client.revokeToken()
client.account().profile()
client.account().following()
client.account().emailAddress()
client.account().preferences()
client.account().kidMode()
client.account().timeline()
client.board().connect()
client.board().challenge()
client.board().challengeKeepAlive()
client.board().challengeAI()
client.board().acceptChallenge()
client.board().declineChallenge()
client.board().cancelChallenge()
client.board().seekCorrespondence()
client.board().seekRealTime()
client.board().connectToGame()
client.board().move()
client.board().abort()
client.board().resign()
client.board().handleDrawOffer()
client.board().handleTakebackOffer()
client.board().claimDraw()
client.board().claimVictory()
client.board().berserk()
client.board().chat()
client.board().chatSpectators()
client.board().fetchChat()
client.bot().upgradeToBotAccount()
client.bot().connect()
client.bot().challenge()
client.bot().challengeKeepAlive()
client.bot().challengeAI()
client.bot().acceptChallenge()
client.bot().declineChallenge()
client.bot().cancelChallenge()
client.bot().connectToGame()
client.bot().move()
client.bot().abort()
client.bot().resign()
client.bot().handleDrawOffer()
client.bot().handleTakebackOffer()
client.bot().claimDraw()
client.bot().claimVictory()
client.bot().chat()
client.bot().chatSpectators()
client.bot().fetchChat()
client.broadcasts().create()
client.broadcasts().update()
client.broadcasts().createRound()
client.broadcasts().updateRound()
client.broadcasts().resetRound()
client.broadcasts().pushPgnByRoundId()
client.broadcasts().myRounds()
client.challenges().connect()
client.challenges().challenges()
client.challenges().challenge()
client.challenges().challengeKeepAlive()
client.challenges().challengeAI()
client.challenges().acceptChallenge()
client.challenges().declineChallenge()
client.challenges().cancelChallenge()
client.challenges().show()
client.challenges().addTimeToGame()
client.challenges().bulk()
client.challenges().bulks()
client.challenges().createBulk()
client.challenges().startBulk()
client.challenges().cancelBulk()
client.challenges().startClocksOfGame()
client.externalEngine().list()
client.externalEngine().get()
client.externalEngine().create()
client.externalEngine().update()
client.externalEngine().delete()
client.games().bookmarked()
client.games().ongoing()
client.games().imported()
client.games().byBulkId()
client.puzzles().activity()
client.puzzles().createAndJoinRace()
client.puzzles().puzzleDashboard()
client.puzzles().replay()
client.studies().importPgn()
client.studies().deleteStudyChapter()
client.studies().updateStudyChapterTags()
client.teams().joinTeam()
client.teams().leaveTeam()
client.teams().messageTeam()
client.teams().kickFromTeam()
client.teams().requests()
client.teams().requestsDeclined()
client.teams().requestAccept()
client.teams().requestDecline()
client.tournaments().joinArena()
client.tournaments().joinSwiss()
client.tournaments().withdrawArena()
client.tournaments().withdrawSwiss()
client.tournaments().createArena()
client.tournaments().createSwiss()
client.tournaments().updateArena()
client.tournaments().updateSwiss()
client.tournaments().scheduleNextRoundSwiss()
client.tournaments().terminateArena()
client.tournaments().terminateSwiss()
client.tournaments().generateUserEntryCodes()
client.tournaments().updateTeamBattle()
client.users().sendMessageToUser()
client.users().followUser()
client.users().unfollowUser()
client.users().blockUser()
client.users().unblockUser()
client.users().writeNoteAboutUser()
client.users().readNotesAboutUser()Checkout the JavaDoc for details.
The latest version is compiled for Java 25, with the coordinates
io.github.tors42:chariot:0.2.0, so in a Maven project the following
dependency can be added to the pom.xml:
<dependency>
<groupId>io.github.tors42</groupId>
<artifactId>chariot</artifactId>
<version>0.2.0</version>
</dependency>The latest version compiled for Java 21 is 0.1.21
Here is a link to a simple example Maven project application https://github.com/tors42/chariot-example which can be imported into an IDE in order to get things like code completion support and other good stuff.
JShell is a tool which can be used to interactively execute Java code.
The tool is included in JDK archives, which can be downloaded and unpacked from https://jdk.java.net/
$ jshell | Welcome to JShell -- Version 25 | For an introduction type: /help intro jshell>
Tell JShell to download the latest release of chariot and make it available in the JShell environment,
jshell> Files.write(Path.of("chariot-0.2.0.jar"), URI.create("https://repo1.maven.org/maven2/io/github/tors42/chariot/0.2.0/chariot-0.2.0.jar").toURL().openStream().readAllBytes());
$1 ==> chariot-0.2.0.jar
jshell> /env --module-path chariot-0.2.0.jar --add-module chariot
| Setting new options and restoring state.
jshell>
Copy/paste the following example code,
import chariot.Client;
var client = Client.basic();
IO.println(client.teams().byTeamId("lichess-swiss").maybe()
.map(team -> "Team %s has %d members!".formatted(team.name(), team.nbMembers()))
.orElse("Couldn't find team!"));jshell> import chariot.Client;
...>
...> var client = Client.basic();
...> IO.println(client.teams().byTeamId("lichess-swiss").maybe()
...> .map(team -> "Team %s has %d members!".formatted(team.name(), team.nbMembers()))
...> .orElse("Couldn't find team!"));
client ==> chariot.internal.impl.ClientImpl@954b04f
Team Lichess Swiss has 643763 members!
jshell>
Tip, it is possible to use the tab key to get code completion to discover the API.
For instance, after writing client.teams(). and pressing the tab key,
jshell> client.teams().<press tab key> arenaByTeamId( byTeamId( byUserId( equals( getClass() hashCode() notify() notifyAll() numberOfTeams() popularTeams() popularTeamsByPage( search( searchByPage( swissByTeamId( toString() usersByTeamId( usersByTeamIdFull( wait( jshell> client.teams().numberOfTeams(); $4 ==> 377439 jshell> /exit | Goodbye
Build with latest Java. A JDK archive can be downloaded and unpacked from https://jdk.java.net/
$ java -version openjdk version "25.0.1" 2025-10-21 OpenJDK Runtime Environment (build 25.0.1+8-27) OpenJDK 64-Bit Server VM (build 25.0.1+8-27, mixed mode, sharing) $ ./build.java 78 successful basic tests 0 failed tests
The resulting artifact, out/modules/chariot-0.0.1-SNAPSHOT.jar, will be compatible with Java release 25
An example which uses a token to authenticate in order to be able to create a Swiss tournament
package res;
import module chariot;
import module java.base;
void main() {
var client = Client.auth("my-token");
var tomorrow = ZonedDateTime.now().plusDays(1).with(
LocalTime.parse("17:00"));
String teamId = "my-team-id";
var result = client.tournaments().createSwiss(teamId, params -> params
.clockBlitz5m3s()
.name("My 5+3 Swiss")
.rated(false)
.description("Created via API")
.startsAt(tomorrow));
IO.println(result);
}$ java -p out/modules --add-modules chariot res/Example.java Some[value=Swiss[id=vLx22Ff1, name=My 5+3 Swiss, createdBy=test, startsAt=2022-03-29T17:00:00.000+02:00, status=created, nbOngoing=0, nbPlayers=0, nbRounds=9, round=0, rated=false, variant=standard, clock=Clock[limit=300, increment=3], greatPlayer=null, nextRound=NextRound[at=2022-03-29T17:00:00.000+02:00, in=62693], quote=null]]
An example which feeds moves to a Board in order to track FEN updates, and "draws" the board with text.
import module chariot;
void main() {
Board initialBoard = Board.ofStandard();
List<String> validMovesUCI = initialBoard.validMoves().stream()
.sorted()
.toList();
List<String> validMovesSAN = validMovesUCI.stream()
.map(initialBoard::toSAN)
.toList();
String movesToPlay = "e4 e5 Nf3 Nc6"; // (UCI also ok, "e2e4 e7e5 g1f3 b8c6")
Board resultingBoard = initialBoard.play(movesToPlay);
IO.println(String.join("\n",
"Initial FEN: " + initialBoard.toFEN(),
"Initial Board:\n" + DefaultBoard.render(initialBoard),
"Valid moves (UCI): " + validMovesUCI,
"Valid moves (SAN): " + validMovesSAN.stream().map("%4s"::formatted).toList(),
"Playing: " + movesToPlay,
"Resulting FEN: " + resultingBoard.toFEN(),
"Resulting Board:\n" + DefaultBoard.render(resultingBoard),
"Board (letter, frame, coordinates):\n" +
DefaultBoard.render(resultingBoard, c -> c.letter().frame().coordinates())
));
}
long costOfThisProgramBecomingSkyNet() {
return Long.MAX_VALUE; // https://xkcd.com/534/
}$ java -p out/modules --add-modules chariot res/FEN.java
Initial FEN: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
Initial Board:
♜ ♞ ♝ ♛ ♚ ♝ ♞ ♜
♟ ♟ ♟ ♟ ♟ ♟ ♟ ♟
♙ ♙ ♙ ♙ ♙ ♙ ♙ ♙
♖ ♘ ♗ ♕ ♔ ♗ ♘ ♖
Valid moves (UCI): [a2a3, a2a4, b1a3, b1c3, b2b3, b2b4, c2c3, c2c4, d2d3, d2d4, e2e3, e2e4, f2f3, f2f4, g1f3, g1h3, g2g3, g2g4, h2h3, h2h4]
Valid moves (SAN): [ a3, a4, Na3, Nc3, b3, b4, c3, c4, d3, d4, e3, e4, f3, f4, Nf3, Nh3, g3, g4, h3, h4]
Playing: e4 e5 Nf3 Nc6
Resulting FEN: r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3
Resulting Board:
♜ ♝ ♛ ♚ ♝ ♞ ♜
♟ ♟ ♟ ♟ ♟ ♟ ♟
♞
♟
♙
♘
♙ ♙ ♙ ♙ ♙ ♙ ♙
♖ ♘ ♗ ♕ ♔ ♗ ♖
Board (letter, frame, coordinates):
┌───┬───┬───┬───┬───┬───┬───┬───┐
8 │ r │ │ b │ q │ k │ b │ n │ r │
├───┼───┼───┼───┼───┼───┼───┼───┤
7 │ p │ p │ p │ p │ │ p │ p │ p │
├───┼───┼───┼───┼───┼───┼───┼───┤
6 │ │ │ n │ │ │ │ │ │
├───┼───┼───┼───┼───┼───┼───┼───┤
5 │ │ │ │ │ p │ │ │ │
├───┼───┼───┼───┼───┼───┼───┼───┤
4 │ │ │ │ │ P │ │ │ │
├───┼───┼───┼───┼───┼───┼───┼───┤
3 │ │ │ │ │ │ N │ │ │
├───┼───┼───┼───┼───┼───┼───┼───┤
2 │ P │ P │ P │ P │ │ P │ P │ P │
├───┼───┼───┼───┼───┼───┼───┼───┤
1 │ R │ N │ B │ Q │ K │ B │ │ R │
└───┴───┴───┴───┴───┴───┴───┴───┘
a b c d e f g h
A list of applications using Chariot,
Bobby Chess Engine with Lichess Bot integration (Java)
Lichess Rating Graph Visualize rating (JavaFX)
Chesslise Discord Bot which allows users to play, learn, and watch chess (Discord)
Team Check Visualize team members (Swing)
charibot Application to control a Lichess BOT account (makes random moves) (Java) @charibot
jc Watch the featured LichessTV game in terminal or Play a casual Rapid game with the Board API (Swing/Text)
ee External Engine - Use local desktop chess engine in Lichess Analysis web browser (Swing)
JBang Examples Various example scripts (JBang)
Challenge AI Example OAuth2 PKCE example (Web Application)
Playground GitHub Codespaces repo to write code in browser
For any questions and/or feedback, feel free to open an issue in this project. Or use the Discussions feature of GitHub. Another means of contact could be through the Lichess Discord server, look for the #lichess-api-support channel.