Skip to main content

​
Upgrade to Bot Account

Bot accounts must be used with API access tokens and cannot play using the web interface.

​
POST /api/bot/account/upgrade

Upgrade your account to a bot account. Once upgraded, the account can:
  • Play games using the Bot API
  • Connect to the event stream for incoming challenges
  • Make moves programmatically via API
This action is irreversible. Bot accounts:
  • Cannot play games via the web interface
  • Cannot participate in tournaments (unless specifically for bots)
  • Cannot join teams after upgrading
  • Will be automatically withdrawn from all tournaments and Swiss events

​
Authentication

Requires OAuth token with bot:play scope.

​
Request

curl -X POST https://lichess.org/api/bot/account/upgrade \
  -H "Authorization: Bearer <your_token>"

​
Response

​
ok
boolean
Success status
{
  "ok": true
}

​
What Happens on Upgrade

  1. Tournament Withdrawal: Automatically withdraws from all active tournaments
  2. Swiss Withdrawal: Withdraws from all Swiss tournaments
  3. Streamer Status: Removes streamer status if present
  4. Team Membership: Existing team memberships remain, but cannot join new teams
  5. Preferences: Bot-specific preferences are applied
  6. User Cache: Light user cache is invalidated

​
Get Bot Account Info

​
GET /api/account

Get the profile information for the authenticated bot account.
Avoid polling this endpoint. Use GET /api/stream/event instead to receive real-time updates.

​
Authentication

Requires OAuth token with any scope.

​
Request

curl https://lichess.org/api/account \
  -H "Authorization: Bearer <your_token>"

​
Response

​
id
string
User ID (lowercase username)
​
username
string
Display username
​
title
string
User title (will be “BOT” for bot accounts)
​
online
boolean
Whether the user is currently online
​
perfs
object
Performance ratings for each game variant and time control
​
createdAt
integer
Account creation timestamp (milliseconds since epoch)
​
profile
object
User profile information
{
  "id": "mybot",
  "username": "MyBot",
  "title": "BOT",
  "online": true,
  "perfs": {
    "blitz": {
      "games": 2340,
      "rating": 1681,
      "rd": 30,
      "prog": 10
    },
    "rapid": {
      "games": 340,
      "rating": 1756,
      "rd": 45,
      "prog": -5
    }
  },
  "createdAt": 1290415680000,
  "profile": {
    "country": "US",
    "bio": "Powered by Stockfish 16"
  },
  "seenAt": 1710331200000,
  "playTime": {
    "total": 3296340,
    "tv": 12340
  },
  "url": "https://lichess.org/@/MyBot",
  "count": {
    "all": 9265,
    "rated": 7157,
    "ai": 0,
    "draw": 340,
    "drawH": 331,
    "loss": 4480,
    "lossH": 4207,
    "win": 4445,
    "winH": 4378
  }
}

​
Best Practices

​
Bot Account Guidelines

  1. Fair Play: Ensure your bot follows Lichess Terms of Service
  2. Engine Attribution: Clearly state which engine your bot uses in the profile
  3. Rate Limiting: Respect API rate limits to avoid being throttled
  4. Connection Management: Use persistent connections for event streams
  5. Graceful Shutdown: Handle disconnections and reconnect appropriately

​
Error Handling

Always check response status codes:
  • 200 - Success
  • 400 - Bad request (e.g., managed account cannot be bot)
  • 401 - Unauthorized (invalid or missing token)
  • 429 - Too many requests (rate limited)

​
Example: Complete Bot Setup

import requests
import time

class LichessBot:
    def __init__(self, token):
        self.token = token
        self.headers = {"Authorization": f"Bearer {token}"}
        self.base_url = "https://lichess.org"
    
    def upgrade_to_bot(self):
        """Upgrade account to bot (irreversible!)"""
        response = requests.post(
            f"{self.base_url}/api/bot/account/upgrade",
            headers=self.headers
        )
        
        if response.status_code == 200:
            print("Successfully upgraded to bot account")
            return True
        else:
            print(f"Upgrade failed: {response.json()}")
            return False
    
    def get_profile(self):
        """Get bot account profile"""
        response = requests.get(
            f"{self.base_url}/api/account",
            headers=self.headers
        )
        
        if response.status_code == 200:
            profile = response.json()
            print(f"Bot: {profile['username']}")
            print(f"Rating (blitz): {profile['perfs']['blitz']['rating']}")
            return profile
        else:
            print(f"Failed to get profile: {response.status_code}")
            return None

# Usage
bot = LichessBot("lip_yourtoken")

# First time setup - uncomment to upgrade
# bot.upgrade_to_bot()

# Get bot info
profile = bot.get_profile()

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us