aiolichess

Async Python client for the Lichess REST API.

Installation

pip install aiolichess

Quick Start

import asyncio
from aiolichess import AioLichess

async def main():
    client = AioLichess()
    user = await client.get_all(token="your_pat_here")

    print(user.username)
    print(user.perfs["blitz"].rating)
    print(user.count.win)

    await client.close()

asyncio.run(main())

With an external session

import aiohttp
from aiolichess import AioLichess

async with aiohttp.ClientSession() as session:
    client = AioLichess(session=session)
    user = await client.get_all(token="your_pat_here")

API Reference

AioLichess(session=None)

The main client class.

await client.get_all(token)

Fetches all account information for the authenticated user via /api/account.

Returns a LichessUser object.

await client.get_user_id(token)

Fetches only the user ID of the authenticated user.

Returns a str.

user_id = await client.get_user_id(token="your_pat_here")
print(user_id)  # "drnykterstien"

await client.get_username(token)

Fetches only the username of the authenticated user.

Returns a str.

username = await client.get_username(token="your_pat_here")
print(username)  # "DrNykterstein"

await client.get_statistics(token)

Fetches rating and game count statistics across all formats.

Returns a LichessStatistics object.

stats = await client.get_statistics(token="your_pat_here")
print(stats.blitz_rating)
print(stats.rapid_games)
print(stats.puzzle_rating)

await client.close()

Closes the session. Only closes if the session was created internally — never closes an externally provided session.

Models

LichessUser

LichessPerf

LichessProfile

LichessCount

LichessStatistics

Rating and games-played counts across every perf exposed by /api/account. Any perf the user has never played is reported as None.

Exceptions

License

GPL-3.0