# Lichess API
> Lichess as an API — the open-source chess platform, returned as clean JSON, no key. Look up any player's profile (titles, ratings across bullet, blitz, rapid and classical, game counts, country, FIDE rating), their rating history per variant and online status; pull the top players for any performance type; fetch a user's recent games with openings, clocks, results and full move lists; get a Stockfish cloud evaluation of any position by FEN (best lines, centipawn or mate scores); serve the daily puzzle or any puzzle by id (with solution and themes); and list current, upcoming and finished tournaments. Live data straight from lichess.org. Distinct from Chess.com player stats: Lichess is its own platform with cloud engine analysis, a puzzle database and arena tournaments — ideal for chess apps, coaching tools, analysis boards, bots and leaderboards. 9 data endpoints. Authenticated with an x-oanor-key; fair-use rate limits per plan.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/lichess-api/..."
```

## Pricing
- **Free** (Free) — 3,500 calls/Mo, 5 req/s
- **Starter** ($7/Mo) — 55,000 calls/Mo, 15 req/s
- **Pro** ($27/Mo) — 320,000 calls/Mo, 30 req/s
- **Mega** ($89/Mo) — 1,400,000 calls/Mo, 80 req/s

## Endpoints

### Players

#### `GET /v1/leaderboard` — Top players for a perf

**Parameters:**
- `perf` (query, optional, string) — bullet, blitz, rapid, classical … Example: `blitz`
- `n` (query, optional, string) — How many (1–200) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/leaderboard?perf=blitz&n=10"
```

**Response:**
```json
{
    "data": {
        "perf": "blitz",
        "count": 10,
        "users": [
            {
                "id": "asdert9",
                "online": false,
                "rating": 3042,
                "progress": 11,
                "username": "asdert9"
            },
            {
                "id": "wonderland305",
                "online": false,
                "rating": 3017,
                "progress": -1,
                "username": "wonderland305"
            },
            {
                "id": "cutemouse83",
                "title": "GM",
                "online": false,
                "rating": 2989,
                "progress": 12,
                "username": "cutemouse83"
            },
            {
                "id": "lu_shanglei",
                "online": false,
                "rating": 2944,
                "progress": -19,
                "username": "Lu_Shanglei"
            },
            {
                "id": "ivy_25",
                "online": false,
                "rating": 2937,
                "progress": 26,
                "username": "ivy_25"
            },
            {
                "id": "polyclinical",
                "online": false,
                "rating": 2928,
                "progress": 7,
                "username": "Polyclinical"
            },
            {
                "id": "fmshawnrl123",
                "title": "GM",
                "online": false,
                "rating": 2928,
                "progr
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user` — Player profile

**Parameters:**
- `username` (query, required, string) — Lichess username Example: `DrNykterstein`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/user?username=DrNykterstein"
```

**Response:**
```json
{
    "data": {
        "user": {
            "id": "drnykterstein",
            "url": "https://lichess.org/@/DrNykterstein",
            "perfs": {
                "blitz": {
                    "rd": 158,
                    "games": 606,
                    "rating": 3153,
                    "progress": 37,
                    "provisional": true
                },
                "rapid": {
                    "rd": 150,
                    "games": 0,
                    "rating": 2500,
                    "progress": 0,
                    "provisional": true
                },
                "atomic": {
                    "rd": 258,
                    "games": 25,
                    "rating": 2160,
                    "progress": 85,
                    "provisional": true
                },
                "bullet": {
                    "rd": 75,
                    "games": 9583,
                    "rating": 3243,
                    "progress": -14,
                    "provisional": false
                },
                "chess960": {
                    "rd": 187,
                    "games": 129,
                    "rating": 2541,
                    "progress": -26,
                    "provisional": true
                },
                "classical": {
                    "rd": 150,
                    "games": 0,
                    "rating": 2500,
                    "progress": 0,
                    "provisional": true
                },
       
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user/rating-history` — Rating history

**Parameters:**
- `username` (query, required, string) — Lichess username Example: `DrNykterstein`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/user/rating-history?username=DrNykterstein"
```

**Response:**
```json
{
    "data": {
        "history": [
            {
                "perf": "UltraBullet",
                "points": [
                    {
                        "date": "2019-07-13",
                        "rating": 2519
                    },
                    {
                        "date": "2020-03-23",
                        "rating": 2413
                    },
                    {
                        "date": "2020-08-29",
                        "rating": 2406
                    }
                ]
            },
            {
                "perf": "Bullet",
                "points": [
                    {
                        "date": "2018-12-15",
                        "rating": 2864
                    },
                    {
                        "date": "2019-01-04",
                        "rating": 2970
                    },
                    {
                        "date": "2019-01-05",
                        "rating": 3117
                    },
                    {
                        "date": "2019-01-07",
                        "rating": 3009
                    },
                    {
                        "date": "2019-01-29",
                        "rating": 2987
                    },
                    {
                        "date": "2019-01-30",
                        "rating": 3091
                    },
                    {
                        "date": "2019-01-31",
                        "rating": 31
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/users/status` — Online status (up to 50)

**Parameters:**
- `ids` (query, required, string) — Comma-separated usernames Example: `DrNykterstein,Hikaru`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/users/status?ids=DrNykterstein%2CHikaru"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "users": [
            {
                "id": "drnykterstein",
                "name": "DrNykterstein",
                "title": "GM",
                "online": false,
                "patron": true,
                "playing": false,
                "streaming": false
            },
            {
                "id": "hikaru",
                "name": "Hikaru",
                "online": false,
                "patron": false,
                "playing": false,
                "streaming": false
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:57.680Z",
        "request_id": "a49bbd04-b691-4446-b3bf-f9700db7cdfc"
    },
    "status": "ok",
    "message": "Status retrieved successfully",
    "success": true
}
```

### Games

#### `GET /v1/user/games` — A user's recent games

**Parameters:**
- `username` (query, required, string) — Lichess username Example: `DrNykterstein`
- `max` (query, optional, string) — Max games (1–50) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/user/games?username=DrNykterstein&max=10"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "games": [
            {
                "id": "kAdOQKeh",
                "url": "https://lichess.org/kAdOQKeh",
                "perf": "blitz",
                "black": {
                    "user": "DrNykterstein",
                    "rating": 3145,
                    "rating_diff": 8
                },
                "clock": {
                    "total": 180,
                    "initial": 180,
                    "increment": 0
                },
                "moves": "e4 Nf6 e5 Nd5 Nc3 Nxc3 dxc3 d6 Nf3 Nc6 Bb5 a6 Bxc6+ bxc6 O-O f6 exf6 exf6 Nd4 Qd7 Qh5+ g6 Qf3 Kf7 Nxc6 Bb7 Nd8+ Rxd8 Qxb7 Qb5 Qxc7+ Rd7 c4 Rxc7 cxb5 axb5 c3 Be7 Rd1 Ra8 a3 f5 Be3 Ke6 Rd3 Bf6 Rad1 Rc6 Bf4 Be5 Re1 Kf6 Bxe5+ dxe5 Rd5 e4 Rxb5 Rd6 g3 Rd2 c4 Rc2 c5 Rd8 Rb6+ Kg5 Rd6 Ra8 c6 Rxb2 Rc1 Rc8 c7 Rb7 Rdc6 Ra7 R1c3 f4 R6c5+ Kg4 gxf4 Kxf4 Kg2 g5 R5c4 Ke5 Rc5+ Kf4 f3 exf3+ Kf2 Ke4 R5c4+ Kf5 Kxf3 h5 Rc5+ Ke6 Rc6+ Kd7 Ke4 g4 Kd5 Ra5+ R6c5 Rxc7 Rxa5 Rxc3 Ke4 Rh3 Rd5+ Ke6 Rd2 Kf6 Kf4 Rf3+ Ke4 Rxa3 Kf4 Rf3+ Ke4 Kg5 Rg2 Kh4 Ke5 Kh3 Rd2 h4 Ke4 Rf8 Ke3 g3 hxg3 hxg3 Rd1 g2",
                "rated": true,
                "speed": "blitz",
                "white": {
                    "user": "respects_55",
                    "rating": 2644,
                    "rating_diff": -5
                },
                "status": "resign",
                "winner": "black",
                "opening": {
                    "eco": "B02",
                    "ply": 5,
   
…(truncated, see openapi.json for full schema)
```

### Analysis

#### `GET /v1/cloud-eval` — Cloud engine evaluation

**Parameters:**
- `fen` (query, required, string) — Position in FEN Example: `rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1`
- `multi_pv` (query, optional, string) — Number of lines (1–5) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/cloud-eval?fen=rnbqkbnr%2Fpppppppp%2F8%2F8%2F8%2F8%2FPPPPPPPP%2FRNBQKBNR+w+KQkq+-+0+1&multi_pv=1"
```

**Response:**
```json
{
    "data": {
        "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
        "pvs": [
            {
                "cp": 19,
                "moves": "e2e4 e7e5 g1f3 b8c6 f1c4 g8f6 d2d3 f8c5 e1h1 d7d6"
            }
        ],
        "depth": 75,
        "knodes": 695524
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:58.279Z",
        "request_id": "bb49781d-5f44-46b8-b341-401d1561aedf"
    },
    "status": "ok",
    "message": "Evaluation retrieved successfully",
    "success": true
}
```

### Puzzles

#### `GET /v1/puzzle` — Puzzle by id

**Parameters:**
- `id` (query, required, string) — Lichess puzzle id Example: `nn1b9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/puzzle?id=nn1b9"
```

**Response:**
```json
{
    "data": {
        "puzzle": {
            "id": "nn1b9",
            "game": {
                "id": "CL8bOq5q",
                "pgn": "e4 e5 Nf3 Nf6 d4 exd4 e5 Ne4 Nxd4 d5 Bd3 Bc5 c3 Nc6 Nxc6 bxc6 Bxe4 dxe4 Qxd8+ Kxd8 Nd2 e3 fxe3 Bxe3 Nf3 Bxc1 Rxc1 Be6 b3 a5 Kf2 a4 Nd4 Bd5 c4 c5 cxd5 cxd4 Rc4 axb3 axb3 Re8 Re1 Ra2+ Kg3 Rb2 Rxd4 Rxb3+ Kf4 Kd7 Rc1 Rb2 Rdc4 Rc8 R1c2 Rxc2 Rxc2 c6 dxc6+ Rxc6 Rxc6 Kxc6 Kf5 Kd7 g4 Ke7 h4 h6 g5 g6+ Ke4",
                "url": "https://lichess.org/CL8bOq5q",
                "perf": "Rapid",
                "clock": "10+0",
                "rated": true,
                "players": [
                    {
                        "id": "l06chess",
                        "name": "l06chess",
                        "color": "white",
                        "rating": 1894
                    },
                    {
                        "id": "thinklikegrandmaster",
                        "name": "Thinklikegrandmaster",
                        "color": "black",
                        "rating": 1865
                    }
                ]
            },
            "plays": 44173,
            "rating": 2019,
            "themes": [
                "veryLong",
                "endgame",
                "zugzwang",
                "crushing",
                "pawnEndgame"
            ],
            "solution": [
                "h6g5",
                "h4g5",
                "e7e6",
                "e4f4",
                "e6d5",
               
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/puzzle/daily` — Daily puzzle

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/puzzle/daily"
```

**Response:**
```json
{
    "data": {
        "puzzle": {
            "id": "nn1b9",
            "game": {
                "id": "CL8bOq5q",
                "pgn": "e4 e5 Nf3 Nf6 d4 exd4 e5 Ne4 Nxd4 d5 Bd3 Bc5 c3 Nc6 Nxc6 bxc6 Bxe4 dxe4 Qxd8+ Kxd8 Nd2 e3 fxe3 Bxe3 Nf3 Bxc1 Rxc1 Be6 b3 a5 Kf2 a4 Nd4 Bd5 c4 c5 cxd5 cxd4 Rc4 axb3 axb3 Re8 Re1 Ra2+ Kg3 Rb2 Rxd4 Rxb3+ Kf4 Kd7 Rc1 Rb2 Rdc4 Rc8 R1c2 Rxc2 Rxc2 c6 dxc6+ Rxc6 Rxc6 Kxc6 Kf5 Kd7 g4 Ke7 h4 h6 g5 g6+ Ke4",
                "url": "https://lichess.org/CL8bOq5q",
                "perf": "Rapid",
                "clock": "10+0",
                "rated": true,
                "players": [
                    {
                        "id": "l06chess",
                        "name": "l06chess",
                        "color": "white",
                        "rating": 1894
                    },
                    {
                        "id": "thinklikegrandmaster",
                        "name": "Thinklikegrandmaster",
                        "color": "black",
                        "rating": 1865
                    }
                ]
            },
            "plays": 44108,
            "rating": 1941,
            "themes": [
                "veryLong",
                "endgame",
                "zugzwang",
                "crushing",
                "pawnEndgame"
            ],
            "solution": [
                "h6g5",
                "h4g5",
                "e7e6",
                "e4f4",
                "e6d5",
               
…(truncated, see openapi.json for full schema)
```

### Tournaments

#### `GET /v1/tournaments` — Tournaments

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/tournaments"
```

**Response:**
```json
{
    "data": {
        "created": [
            {
                "id": "X1XrRdD5",
                "url": "https://lichess.org/tournament/X1XrRdD5",
                "name": "Weekly UltraBullet Arena",
                "perf": "UltraBullet",
                "clock": {
                    "limit": 15,
                    "increment": 0
                },
                "rated": true,
                "minutes": 120,
                "variant": "standard",
                "starts_at": 1780851600000,
                "nb_players": 58,
                "finishes_at": 1780858800000
            },
            {
                "id": "y9JeQu9a",
                "url": "https://lichess.org/tournament/y9JeQu9a",
                "name": "Hourly Antichess Arena",
                "perf": "Antichess",
                "clock": {
                    "limit": 180,
                    "increment": 2
                },
                "rated": true,
                "minutes": 57,
                "variant": "antichess",
                "starts_at": 1780851602500,
                "nb_players": 4,
                "finishes_at": 1780855022500
            },
            {
                "id": "G52yJAPW",
                "url": "https://lichess.org/tournament/G52yJAPW",
                "name": "≤1500 Bullet Arena",
                "perf": "Bullet",
                "clock": {
                    "limit": 60,
                    "increment": 0
                },
                "rated": true,
        
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lichess-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "lichess-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/user": "User profile by username.",
            "GET /v1/puzzle": "A puzzle by id.",
            "GET /v1/cloud-eval": "Cloud engine evaluation of a FEN.",
            "GET /v1/user/games": "A user's recent games (max=).",
            "GET /v1/leaderboard": "Top players for a perf (perf=, n=).",
            "GET /v1/tournaments": "Current, upcoming and finished tournaments.",
            "GET /v1/puzzle/daily": "The daily puzzle.",
            "GET /v1/users/status": "Online status for up to 50 users (ids=).",
            "GET /v1/user/rating-history": "A user's rating history per variant."
        },
        "description": "Lichess: user profiles, rating history, online status, performance leaderboards, recent games, cloud engine evaluation, the daily puzzle and puzzles by id, and tournaments. Real live data, no key."
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:58.691Z",
        "request_id": "c2aff082-d3f5-4c28-a726-a8a5baa1c779"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/lichess-api
OpenAPI spec: https://www.oanor.com/api/lichess-api/openapi.json