{"openapi":"3.1.0","info":{"title":"Chess.com API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/chess-api","description":"oanor gateway"}],"tags":[{"name":"Chess"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/leaderboards":{"get":{"operationId":"get_v1_leaderboards","tags":["Chess"],"summary":"Leaderboard top players","description":"","parameters":[{"name":"category","in":"query","required":false,"description":"live_blitz live_rapid live_bullet daily tactics …","schema":{"type":"string"},"example":"live_blitz"},{"name":"limit","in":"query","required":false,"description":"Max 1-50","schema":{"type":"string"},"example":"20"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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,"title":"GM","country":"IN","username":"GHANDEEVAM2003"},{"url":"https://www.chess.com/member/Philippians46","rank":7,"score":3290,"title":"GM","country":"IT","username":"Philippians46"},{"url":"https://www.chess.com/member/GMWSO","rank":8,"score":3278,"title":"GM","country":"US","username":"GMWSO"},{"url":"https://www.chess.com/member/DenLaz","rank":9,"score":3275,"title":"GM","country":"BY","username":"DenLaz"},{"url":"https://www.chess.com/member/Firouzja2003","rank":10,"score":3270,"title":"GM","country":"FR","username":"Firouzja2003"},{"url":"https://www.chess.com/member/rpragchess","rank":11,"score":3266,"title":"GM","country":"IN","username":"rpragchess"},{"url":"https://www.chess.com/member/ChessWarrior7197","rank":12,"score":3255,"title":"GM","country":"UZ","username":"ChessWarrior7197"},{"url":"https://www.chess.com/member/spicycaterpillar","rank":13,"score":3251,"title":"GM","country":"US","username":"spicycaterpillar"},{"url":"https://www.chess.com/member/HansOnTwitch","rank":14,"score":3250,"title":"GM","country":"US","username":"HansOnTwitch"},{"url":"https://www.chess.com/member/mishanick","rank":15,"score":3249,"title":"GM","country":"RS","username":"mishanick"},{"url":"https://www.chess.com/member/amintabatabaei","rank":16,"score":3247,"title":"GM","country":"IR","username":"amintabatabaei"},{"url":"https://www.chess.com/member/FairChess_on_YouTube","rank":17,"score":3245,"title":"GM","country":"GE","username":"FairChess_on_YouTube"},{"url":"https://www.chess.com/member/LyonBeast","rank":18,"score":3238,"title":"GM","country":"FR","username":"LyonBeast"},{"url":"https://www.chess.com/member/Mykola-Bortnyk","rank":19,"score":3226,"title":"IM","country":"US","username":"Mykola-Bortnyk"},{"url":"https://www.chess.com/member/lachesisQ","rank":20,"score":3226,"title":"GM","country":"RU","username":"lachesisQ"}],"category":"live_blitz"},"meta":{"timestamp":"2026-05-30T05:34:59.591Z","request_id":"5bf3e8e0-1daf-4137-9e6d-75372f529a3b"},"status":"ok","message":"Leaderboards retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/player":{"get":{"operationId":"get_v1_player","tags":["Chess"],"summary":"Player profile","description":"","parameters":[{"name":"username","in":"query","required":true,"description":"Chess.com username","schema":{"type":"string"},"example":"hikaru"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/stats":{"get":{"operationId":"get_v1_stats","tags":["Chess"],"summary":"Player rating stats","description":"","parameters":[{"name":"username","in":"query","required":true,"description":"Chess.com username","schema":{"type":"string"},"example":"hikaru"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":8000,"rps_limit":2,"hard_limit":true},{"slug":"basic","name":"Basic","price_cents_month":800,"monthly_call_quota":120000,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2200,"monthly_call_quota":600000,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":5900,"monthly_call_quota":2500000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/chess-api"}