Getting Started

Getting Started with LichessSharp

This guide will help you get started with the LichessSharp library.

Installation

Install the NuGet package:

dotnet add package LichessSharp

Or via the Package Manager Console:

Install-Package LichessSharp

Basic Usage

Creating a Client

The simplest way to create a client is without authentication:

using LichessSharp;

using var client = new LichessClient();

For authenticated endpoints, provide an access token:

using var client = new LichessClient("lip_your_access_token");

Custom Configuration

For more control, use LichessClientOptions:

var options = new LichessClientOptions
{
    AccessToken = "your-token",
    DefaultTimeout = TimeSpan.FromSeconds(60),

    // Rate limit retry settings
    AutoRetryOnRateLimit = true,
    MaxRateLimitRetries = 5,

    // Transient failure retry settings (DNS errors, connection timeouts, etc.)
    EnableTransientRetry = true,
    MaxTransientRetries = 3,
    TransientRetryBaseDelay = TimeSpan.FromSeconds(1),
    TransientRetryMaxDelay = TimeSpan.FromSeconds(30)
};

using var client = new LichessClient(new HttpClient(), options);

Configuration for Integration Testing

When running integration tests against the live Lichess API, you may encounter rate limits. Enable unlimited rate limit retries to ensure tests wait and complete rather than failing:

var options = new LichessClientOptions
{
    AccessToken = "your-token",
    DefaultTimeout = TimeSpan.FromMinutes(10), // Extended timeout for long waits

    // Enable unlimited retries for rate limits (respects Retry-After header)
    AutoRetryOnRateLimit = true,
    UnlimitedRateLimitRetries = true
};

using var client = new LichessClient(new HttpClient(), options);

This configuration will automatically wait and retry when Lichess returns HTTP 429 (Too Many Requests), respecting the Retry-After header. Use a cancellation token to stop waiting if needed.

Using with Dependency Injection

For ASP.NET Core or other DI-enabled applications:

services.AddHttpClient<ILichessClient, LichessClient>((sp, httpClient) =>
{
    var options = sp.GetRequiredService<IOptions<LichessClientOptions>>().Value;
    return new LichessClient(httpClient, options);
});

Accessing APIs

The client exposes different API areas through properties:

// Account operations
var profile = await client.Account.GetProfileAsync();

// User operations
var user = await client.Users.GetAsync("DrNykterstein");
var statuses = await client.Users.GetStatusAsync(new[] { "DrNykterstein", "Hikaru" });

// Game operations
var game = await client.Games.GetAsync("q7ZvsdUF");

// Puzzle operations
var dailyPuzzle = await client.Puzzles.GetDailyAsync();

Cancellation

All async methods accept a CancellationToken:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));

try
{
    var user = await client.Users.GetAsync("DrNykterstein", cancellationToken: cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Request was cancelled");
}

Streaming

Many endpoints stream data using IAsyncEnumerable:

await foreach (var game in client.Games.StreamUserGamesAsync("DrNykterstein"))
{
    Console.WriteLine($"Game: {game.Id}");

    // You can break early
    if (someCondition)
        break;
}

With cancellation:

using var cts = new CancellationTokenSource();

await foreach (var event in client.Tv.StreamCurrentGameAsync(cts.Token))
{
    Console.WriteLine($"FEN: {event.Fen}");
}

Error Handling

Handle specific error types:

try
{
    var user = await client.Users.GetAsync("nonexistent");
}
catch (LichessNotFoundException)
{
    // User doesn't exist
}
catch (LichessRateLimitException ex)
{
    // Rate limited - wait and retry
    await Task.Delay(ex.RetryAfter ?? TimeSpan.FromMinutes(1));
}
catch (LichessAuthenticationException)
{
    // Invalid or expired token
}
catch (LichessAuthorizationException ex)
{
    // Missing required OAuth scope
    Console.WriteLine($"Need scope: {ex.RequiredScope}");
}
catch (LichessException ex)
{
    // Other API errors
    Console.WriteLine($"API error: {ex.LichessError}");
}

Next Steps

• Authentication - Token management and OAuth scopes
• API Reference - Complete endpoint coverage