# Chess.com API
> Public Chess.com data — player profiles (title, country, followers, join date), rating stats across rapid, blitz, bullet and daily with win/loss/draw records and personal bests, and the live leaderboards. Great for chess apps, dashboards, coaching tools, streamers and esports analytics.

## 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/chess-api/..."
```

## Pricing
- **Free** (Free) — 8,000 calls/Mo, 2 req/s
- **Basic** ($8/Mo) — 120,000 calls/Mo, 8 req/s
- **Pro** ($22/Mo) — 600,000 calls/Mo, 20 req/s
- **Mega** ($59/Mo) — 2,500,000 calls/Mo, 50 req/s

## Endpoints

### Chess

#### `GET /v1/leaderboards` — Leaderboard top players

**Parameters:**
- `category` (query, optional, string) — live_blitz live_rapid live_bullet daily tactics … Example: `live_blitz`
- `limit` (query, optional, string) — Max 1-50 Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chess-api/v1/leaderboards?category=live_blitz&limit=20"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "players": [
            {
                "url": "https://www.chess.com/member/MagnusCarlsen",
                "rank": 1,
                "score": 3373,
                "title": "GM",
                "country": "NO",
                "username": "MagnusCarlsen"
            },
            {
                "url": "https://www.chess.com/member/gurelediz",
                "rank": 2,
                "score": 3335,
                "title": "GM",
                "country": "TR",
                "username": "gurelediz"
            },
            {
                "url": "https://www.chess.com/member/Hikaru",
                "rank": 3,
                "score": 3322,
                "title": "GM",
                "country": "US",
                "username": "Hikaru"
            },
            {
                "url": "https://www.chess.com/member/Polish_fighter3000",
                "rank": 4,
                "score": 3317,
                "title": "GM",
                "country": "PL",
                "username": "Polish_fighter3000"
            },
            {
                "url": "https://www.chess.com/member/nihalsarin",
                "rank": 5,
                "score": 3314,
                "title": "GM",
                "country": "AM",
                "username": "nihalsarin"
            },
            {
                "url": "https://www.chess.com/member/GHANDEEVAM2003",
                "rank": 6,
                "score": 3298
…(truncated, see openapi.json for full schema)
```

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

**Parameters:**
- `username` (query, required, string) — Chess.com username Example: `hikaru`

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

**Response:**
```json
{
    "data": {
        "url": "https://www.chess.com/member/Hikaru",
        "name": "Hikaru Nakamura",
        "title": "GM",
        "avatar": "https://images.chesscomfiles.com/uploads/v1/user/15448422.88c010c1.200x200o.3c5619f5441e.png",
        "joined": "2014-01-06T21:20:58.000Z",
        "league": "Legend",
        "status": "premium",
        "country": "US",
        "location": "Florida",
        "username": "hikaru",
        "verified": false,
        "followers": 1392718,
        "is_streamer": true,
        "last_online": "2026-05-29T09:23:22.000Z"
    },
    "meta": {
        "timestamp": "2026-05-30T05:35:00.100Z",
        "request_id": "1b5c24a9-0597-44d5-b9e9-7c1e1677587f"
    },
    "status": "ok",
    "message": "Player retrieved",
    "success": true
}
```

#### `GET /v1/stats` — Player rating stats

**Parameters:**
- `username` (query, required, string) — Chess.com username Example: `hikaru`

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

**Response:**
```json
{
    "data": {
        "fide": 2814,
        "blitz": {
            "best": 3465,
            "rating": 3322,
            "record": {
                "win": 34665,
                "draw": 4282,
                "loss": 5431
            }
        },
        "daily": {
            "best": 2464,
            "rating": 2239,
            "record": {
                "win": 73,
                "draw": 4,
                "loss": 11
            }
        },
        "rapid": {
            "best": 2927,
            "rating": 2839,
            "record": {
                "win": 201,
                "draw": 209,
                "loss": 67
            }
        },
        "bullet": {
            "best": 3570,
            "rating": 3431,
            "record": {
                "win": 16317,
                "draw": 1089,
                "loss": 2324
            }
        },
        "username": "hikaru",
        "tactics_highest": 2730,
        "puzzle_rush_best": 123
    },
    "meta": {
        "timestamp": "2026-05-30T05:35:00.652Z",
        "request_id": "f7644ca1-8289-4ef3-aaba-878c6f48abb7"
    },
    "status": "ok",
    "message": "Stats retrieved",
    "success": true
}
```


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