Chess.com API: List top players
Lists up to 50 top Chess.com players for a time control, in rank order, with ratings, game records and profile links. Puzzles rankings use puzzle scores.
Unofficial. Not affiliated with or endorsed by Chess.com.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Max Results optional
max_results Maximum number of ranked players, for example 10.
5
Whole number from 1 to 50. Default
50.- Time Control optional
time_control Leaderboard category, for example blitz.
rapid
One of
rapid,blitz,bullet,daily,puzzles. Defaultblitz.
Input as JSON
{ "max_results": 5, "time_control": "rapid"}Output
{ "players": [ { "name": "Manu David", "rank": 1, "wins": 290, "draws": 16, "title": "FM", "losses": 37, "rating": 2966, "country": "India", "username": "ManuDavid2910", "profile_link": "https://www.chess.com/member/ManuDavid2910" }, { "name": "Magnus Carlsen", "rank": 2, "wins": 199, "draws": 125, "title": "GM", "losses": 42, "rating": 2941, "country": "Norway", "username": "MagnusCarlsen", "profile_link": "https://www.chess.com/member/MagnusCarlsen" }, { "name": "Andrey Gutov", "rank": 3, "wins": 157, "draws": 3, "title": "GM", "losses": 1, "rating": 2938, "country": "United States", "username": "GutovAndrey", "profile_link": "https://www.chess.com/member/GutovAndrey" } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"chess.com/list_top_players","input":{"max_results":5,"time_control":"rapid"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "chess.com/list_top_players" , "input": { "max_results": 5, "time_control": "rapid" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "chess.com/list_top_players" , "input": { "max_results": 5, "time_control": "rapid" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run chess.com/list_top_players# with {"max_results":5,"time_control":"rapid"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [], "properties": { "max_results": { "type": "integer", "default": 50, "maximum": 50, "minimum": 1, "description": "Maximum number of ranked players, for example 10." }, "time_control": { "enum": [ "rapid", "blitz", "bullet", "daily", "puzzles" ], "type": "string", "default": "blitz", "description": "Leaderboard category, for example blitz." } }}Output schema
{ "type": "object", "required": [ "players" ], "properties": { "players": { "type": "array", "items": { "type": "object", "required": [ "rank", "username", "name", "title", "country", "rating", "wins", "losses", "draws", "profile_link" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Displayed full name, when available." }, "rank": { "type": [ "integer", "null" ], "description": "Leaderboard position." }, "wins": { "type": [ "integer", "null" ], "description": "Published win count, when available." }, "draws": { "type": [ "integer", "null" ], "description": "Published draw count, when available." }, "title": { "type": [ "string", "null" ], "description": "Chess title, when available." }, "losses": { "type": [ "integer", "null" ], "description": "Published loss count, when available." }, "rating": { "type": [ "integer", "null" ], "description": "Leaderboard rating or puzzle score." }, "country": { "type": [ "string", "null" ], "description": "Displayed country name, when available." }, "username": { "type": "string", "description": "Chess.com username." }, "profile_link": { "type": "string", "description": "Player profile page." } }, "additionalProperties": false } } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
chess.com/list_top_players- Returns
- rank, username, name, title, country, rating, wins, losses, draws, profile link
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method chess.com/list_top_players with the inputs above.
Ask your agent
- Show me the top 10 blitz players on chess.com with their ratings and profile links
- Who are the highest rated bullet players right now? List the top 25 with country and title
- I need a ranked list of the top 50 rapid chess players, including wins, losses and draws
- Give me the current top 15 puzzle rankings by puzzle score, with usernames and countries
- What does the daily chess leaderboard look like? Top 5 players please, with their real names if listed
See more
All Chess.com methodsGets a Chess.com player's public profile, ratings and game records, best puzzle rating and Puzzle Rush best score from a username or member profile link.
chess.com/get_player_statsLists a Chess.com player's completed public games for a month, newest first, with results, ratings, opening and game links.
chess.com/list_recent_gamesLists Twitch games and categories ranked by current live viewers, with content tags, box art and category links.
twitch.tv/list_top_categoriesGets the ATP men's singles world rankings as of the latest published ranking date. Finds one ranked player by name, or returns up to 500 ranked players in rank order.
atptour.com/get_rankingsLists ranked Roblox experiences from a current Charts list. Each game includes players online, approval percentage, creator, icon and game link.
roblox.com/list_top_gamesLists the most-watched live Twitch streams, optionally within a category and language. All-category results are limited to 30 streams; category results allow up to 100.
twitch.tv/list_top_streamsLists Steam's top-selling, discounted, or new and trending games in store order, with prices for a chosen country, review summaries and release dates.
store.steampowered.com/list_top_sellersLists the games with the most players on Steam right now, with current and peak players and prices for a chosen country.
store.steampowered.com/list_most_played