Quick Reference

LichessSharp Quick Reference

Installation

dotnet add package LichessSharp

Creating a Client

using LichessSharp;

// Without authentication (limited endpoints)
using var client = new LichessClient();

// With personal access token
using var client = new LichessClient("lip_xxxxxxxx");

// With custom options
using var client = new LichessClient("lip_xxxxxxxx", new LichessClientOptions
{
    DefaultTimeout = TimeSpan.FromSeconds(60),
    AutoRetryOnRateLimit = true
});

---

API Quick Reference

Account (client.Account)

var profile = await client.Account.GetProfileAsync();
var email = await client.Account.GetEmailAsync();
var prefs = await client.Account.GetPreferencesAsync();
var kidMode = await client.Account.GetKidModeAsync();
await client.Account.SetKidModeAsync(true);

Users (client.Users)

var user = await client.Users.GetAsync("username");
var users = await client.Users.GetManyAsync(new[] { "user1", "user2" });
var statuses = await client.Users.GetRealTimeStatusAsync(new[] { "user1" });
var history = await client.Users.GetRatingHistoryAsync("username");
var top10 = await client.Users.GetAllTop10Async();
var leaders = await client.Users.GetLeaderboardAsync("blitz", 100);
var crosstable = await client.Users.GetCrosstableAsync("user1", "user2");
var streamers = await client.Users.GetLiveStreamersAsync();

Games (client.Games)

var game = await client.Games.ExportAsync("gameId");
var pgn = await client.Games.GetPgnAsync("gameId");
var ongoing = await client.Games.GetOngoingGamesAsync();

// Streaming
await foreach (var g in client.Games.StreamUserGamesAsync("username")) { }
await foreach (var g in client.Games.StreamByUsersAsync(userIds)) { }
await foreach (var move in client.Games.StreamGameMovesAsync("gameId")) { }

Bot (client.Bot)

// Event streams
await foreach (var evt in client.Bot.StreamEventsAsync()) { }
await foreach (var evt in client.Bot.StreamGameAsync(gameId)) { }

// Game actions
await client.Bot.MakeMoveAsync(gameId, "e2e4");
await client.Bot.WriteChatAsync(gameId, ChatRoom.Player, "gl");
await client.Bot.AbortAsync(gameId);
await client.Bot.ResignAsync(gameId);
await client.Bot.HandleDrawAsync(gameId, accept: true);
await client.Bot.ClaimVictoryAsync(gameId);

// Account
await client.Bot.UpgradeAccountAsync();
await foreach (var bot in client.Bot.GetOnlineBotsAsync(50)) { }

Board (client.Board)

// Event streams
await foreach (var evt in client.Board.StreamEventsAsync()) { }
await foreach (var evt in client.Board.StreamGameAsync(gameId)) { }
await foreach (var result in client.Board.SeekAsync(options)) { }

// Game actions
await client.Board.MakeMoveAsync(gameId, "e2e4");
await client.Board.WriteChatAsync(gameId, ChatRoom.Player, "gg");
await client.Board.AbortAsync(gameId);
await client.Board.ResignAsync(gameId);
await client.Board.HandleDrawAsync(gameId, accept: true);
await client.Board.BerserkAsync(gameId);

Challenges (client.Challenges)

var pending = await client.Challenges.GetPendingAsync();
var challenge = await client.Challenges.CreateAsync("opponent", options);
await client.Challenges.AcceptAsync(challengeId);
await client.Challenges.DeclineAsync(challengeId, ChallengeDeclineReason.TooFast);
await client.Challenges.CancelAsync(challengeId);
var aiGame = await client.Challenges.ChallengeAiAsync(options);
var open = await client.Challenges.CreateOpenAsync(options);
await client.Challenges.AddTimeAsync(gameId, 15);

Puzzles (client.Puzzles)

var daily = await client.Puzzles.GetDailyAsync();
var puzzle = await client.Puzzles.GetAsync("puzzleId");
var next = await client.Puzzles.GetNextAsync(angle: "mateIn2");
var batch = await client.Puzzles.GetBatchAsync("mix", nb: 10);
var dashboard = await client.Puzzles.GetDashboardAsync(30);
var storm = await client.Puzzles.GetStormDashboardAsync("username");
await foreach (var activity in client.Puzzles.StreamActivityAsync(50)) { }

Teams (client.Teams)

var team = await client.Teams.GetAsync("teamId");
var popular = await client.Teams.GetPopularAsync(page: 1);
var search = await client.Teams.SearchAsync("chess club");
var userTeams = await client.Teams.GetUserTeamsAsync("username"); // Requires OAuth
await foreach (var member in client.Teams.StreamMembersAsync("teamId")) { }
await client.Teams.JoinAsync("teamId", message: "Please let me join");
await client.Teams.LeaveAsync("teamId");

Relations (client.Relations)

await foreach (var user in client.Relations.StreamFollowingUsersAsync()) { }
await client.Relations.FollowUserAsync("username");
await client.Relations.UnfollowUserAsync("username");
await client.Relations.BlockUserAsync("username");
await client.Relations.UnblockUserAsync("username");

OAuth (client.OAuth)

var (authUrl, codeVerifier) = client.OAuth.CreateAuthorizationRequest(
    clientId: "my-app",
    redirectUri: "http://localhost/callback",
    scopes: new[] { "preference:read", "board:play" }
);

var token = await client.OAuth.GetTokenAsync(new OAuthTokenRequest
{
    Code = authCode,
    CodeVerifier = codeVerifier,
    RedirectUri = "http://localhost/callback",
    ClientId = "my-app"
});

await client.OAuth.RevokeTokenAsync();
var tokenInfo = await client.OAuth.TestTokensAsync(new[] { token1, token2 });

TV (client.Tv)

var channels = await client.Tv.GetChannelsAsync();
await foreach (var game in client.Tv.StreamCurrentTvGameAsync()) { }

Tournaments (client.ArenaTournaments, client.SwissTournaments)

// Arena tournaments
var arena = await client.ArenaTournaments.GetAsync("tournamentId");
await foreach (var standing in client.ArenaTournaments.StreamStandingsAsync("id")) { }

// Swiss tournaments
var swiss = await client.SwissTournaments.GetAsync("swissId");
await foreach (var result in client.SwissTournaments.StreamResultsAsync("id")) { }

Simuls (client.Simuls)

var simuls = await client.Simuls.GetCurrentAsync();
// simuls.Started, simuls.Created, simuls.Finished, simuls.Pending

Studies (client.Studies)

var pgn = await client.Studies.ExportStudyPgnAsync("studyId");
await foreach (var study in client.Studies.StreamUserStudiesAsync("username")) { }
await client.Studies.ImportPgnAsync("studyId", pgn, new StudyImportOptions { Name = "Chapter" });

Broadcasts (client.Broadcasts)

await foreach (var b in client.Broadcasts.StreamOfficialBroadcastsAsync(nb: 10)) { }
var tournament = await client.Broadcasts.GetTournamentAsync("tournamentId");
var pgn = await client.Broadcasts.ExportRoundPgnAsync("roundId");

Messaging (client.Messaging)

await client.Messaging.SendAsync("username", "Hello!");

Analysis (client.Analysis)

var eval = await client.Analysis.GetCloudEvaluationAsync(fen, multiPv: 3);

Opening Explorer (client.OpeningExplorer)

var masters = await client.OpeningExplorer.GetMastersAsync(fen);
var lichess = await client.OpeningExplorer.GetLichessAsync(fen, options);
var player = await client.OpeningExplorer.GetPlayerAsync(fen, "username", options);

Tablebase (client.Tablebase)

var result = await client.Tablebase.LookupAsync(fen);
// result.Category, result.Dtz, result.Moves

FIDE (client.Fide)

var player = await client.Fide.GetPlayerAsync(1503014); // FIDE ID
var results = await client.Fide.SearchPlayersAsync("Carlsen");

Bulk Pairings (client.BulkPairings)

var pairing = await client.BulkPairings.CreateAsync(options);
var pairings = await client.BulkPairings.GetAsync(pairingId);
await client.BulkPairings.StartClocksAsync(pairingId);

External Engine (client.ExternalEngine)

var engines = await client.ExternalEngine.ListAsync();
var engine = await client.ExternalEngine.CreateAsync(registration);
await foreach (var line in client.ExternalEngine.AnalyseAsync("id", request)) { }

---

Polymorphic Event Handling

Bot Game Events

await foreach (var evt in client.Bot.StreamGameAsync(gameId))
{
    switch (evt)
    {
        case BotGameFullEvent full: /* First event */ break;
        case BotGameStateEvent state: /* Move updates */ break;
        case BotChatLineEvent chat: /* Chat messages */ break;
        case BotOpponentGoneEvent gone: /* Opponent left */ break;
    }
}

Board Game Events

await foreach (var evt in client.Board.StreamGameAsync(gameId))
{
    switch (evt)
    {
        case GameFullEvent full: /* First event */ break;
        case GameStateEvent state: /* Move updates */ break;
        case ChatLineEvent chat: /* Chat messages */ break;
        case OpponentGoneEvent gone: /* Opponent left */ break;
    }
}

---

Common Options

ChallengeCreateOptions

new ChallengeCreateOptions
{
    Rated = true,
    ClockLimit = 300,      // 5 minutes in seconds
    ClockIncrement = 3,    // 3 seconds
    Color = ChallengeColor.Random,
    Variant = "standard",  // or "chess960", "crazyhouse", etc.
    Rules = ChallengeRules.NoAbort | ChallengeRules.NoRematch
}

ChallengeAiOptions

new ChallengeAiOptions
{
    Level = 8,             // 1-8
    ClockLimit = 300,
    ClockIncrement = 0,
    Color = ChallengeColor.White
}

ExportGameOptions

new ExportGameOptions
{
    Moves = true,
    PgnInJson = true,
    Clocks = true,
    Evals = true,
    Opening = true
}

SeekOptions

new SeekOptions
{
    Rated = true,
    Time = 5,              // minutes
    Increment = 3,         // seconds
    RatingMin = 1500,
    RatingMax = 2000
}

---

OAuth Scopes

Scope	Description
preference:read	Read preferences
preference:write	Write preferences
email:read	Read email
challenge:read	Read challenges
challenge:write	Create/accept/decline challenges
board:play	Play with Board API
bot:play	Play with Bot API
puzzle:read	Read puzzle activity
team:read	Read team membership
team:write	Join/leave teams
team:lead	Manage teams
follow:read	Read followed users
follow:write	Follow/block users
msg:write	Send messages

---

Performance Types

Key	Description
ultraBullet	UltraBullet
bullet	Bullet
blitz	Blitz
rapid	Rapid
classical	Classical
correspondence	Correspondence
chess960	Chess960
crazyhouse	Crazyhouse
antichess	Antichess
atomic	Atomic
horde	Horde
kingOfTheHill	King of the Hill
racingKings	Racing Kings
threeCheck	Three-check