{"openapi":"3.1.0","info":{"title":"chess402","description":"Pay-per-call chess API. x402 + MPP wrappers around popular Lichess endpoints.","version":"0.1.0","x-guidance":"chess402 exposes a small set of paid chess endpoints that proxy the public\nLichess API. Each request is billed in USDC over x402 (Base) or MPP (Tempo).\n\nEndpoints:\n  POST /api/cloud-eval  body { fen, multiPv?, variant? }  $0.005\n    Returns Stockfish cloud evaluation for a position (depth, eval, PV).\n    `fen` is a standard FEN string. `multiPv` 1-5 (default 1). `variant`\n    one of standard|chess960|crazyhouse|antichess|atomic|horde|kingOfTheHill|\n    racingKings|threeCheck.\n\n  POST /api/masters  body { fen, play?, since?, until?, moves?, topGames? }  $0.003\n    Returns top master-game moves, win rates, and recent master games for\n    a FEN. `play` is a UCI move sequence applied to the FEN. `moves`\n    caps top moves returned (default 12).\n\n  POST /api/user  body { username }  $0.001\n    Returns the Lichess profile snapshot: ratings per perf, country, title,\n    online status, counts. Case-insensitive username.\n\n  POST /api/puzzle/daily  body {}  $0.001\n    Returns today's Lichess daily puzzle: PGN, moves, themes, rating.\n    No parameters required.\n\nEtiquette: backed by the public Lichess API. Respect their rate limits.\nCache results when possible. Credit Lichess in user-facing output.","guidance":"chess402 exposes a small set of paid chess endpoints that proxy the public\nLichess API. Each request is billed in USDC over x402 (Base) or MPP (Tempo).\n\nEndpoints:\n  POST /api/cloud-eval  body { fen, multiPv?, variant? }  $0.005\n    Returns Stockfish cloud evaluation for a position (depth, eval, PV).\n    `fen` is a standard FEN string. `multiPv` 1-5 (default 1). `variant`\n    one of standard|chess960|crazyhouse|antichess|atomic|horde|kingOfTheHill|\n    racingKings|threeCheck.\n\n  POST /api/masters  body { fen, play?, since?, until?, moves?, topGames? }  $0.003\n    Returns top master-game moves, win rates, and recent master games for\n    a FEN. `play` is a UCI move sequence applied to the FEN. `moves`\n    caps top moves returned (default 12).\n\n  POST /api/user  body { username }  $0.001\n    Returns the Lichess profile snapshot: ratings per perf, country, title,\n    online status, counts. Case-insensitive username.\n\n  POST /api/puzzle/daily  body {}  $0.001\n    Returns today's Lichess daily puzzle: PGN, moves, themes, rating.\n    No parameters required.\n\nEtiquette: backed by the public Lichess API. Respect their rate limits.\nCache results when possible. Credit Lichess in user-facing output.","contact":{"name":"chess402","url":"https://chess402.vercel.app"}},"servers":[{"url":"https://chess402.vercel.app"}],"tags":[{"name":"Cloud Eval"},{"name":"Masters"},{"name":"Puzzle"},{"name":"User"}],"paths":{"/api/cloud-eval":{"post":{"operationId":"cloud-eval","summary":"Stockfish cloud evaluation for a FEN position. Returns depth, evaluation, and principal variation(s) when Lichess has the position cached.","tags":["Cloud Eval"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fen":{"type":"string","minLength":15,"maxLength":100,"description":"Standard FEN position string, e.g. 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'"},"multiPv":{"description":"Number of principal variations to return (1-5). Default 1.","type":"integer","minimum":1,"maximum":5},"variant":{"description":"Chess variant. Default 'standard'.","type":"string","enum":["standard","chess960","crazyhouse","antichess","atomic","horde","kingOfTheHill","racingKings","threeCheck"]}},"required":["fen"],"description":"Cloud-eval request: FEN position to analyze plus options."}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"fen":{"type":"string","description":"Echoed FEN that was evaluated."},"knodes":{"description":"Kilonodes searched.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"depth":{"description":"Search depth in plies.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pvs":{"type":"array","items":{"type":"object","properties":{"moves":{"type":"string","description":"Space-separated UCI moves of the principal variation."},"cp":{"description":"Evaluation in centipawns from the side-to-move POV.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mate":{"description":"Mate-in-N from the side-to-move POV, when applicable.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["moves"],"additionalProperties":{}},"description":"Principal variations (one per multiPv)."}},"required":["fen","pvs"],"additionalProperties":{},"description":"Cloud-eval response: depth, knodes, and principal variations."}}}},"402":{"description":"Payment Required"}}}},"/api/puzzle/daily":{"post":{"operationId":"puzzle_daily","summary":"Today's Lichess daily puzzle: source game, themes, initial position, solution moves, and rating.","tags":["Puzzle"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"description":"No parameters required. Send `{}` or an empty body."}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"game":{"type":"object","properties":{"id":{"type":"string","description":"Lichess game id the puzzle was extracted from."},"pgn":{"description":"PGN of the game up to the puzzle position.","type":"string"}},"required":["id"],"additionalProperties":{},"description":"Source game for the puzzle."},"puzzle":{"type":"object","properties":{"id":{"type":"string","description":"Puzzle id."},"rating":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Puzzle difficulty rating."},"solution":{"type":"array","items":{"type":"string"},"description":"Sequence of UCI moves that solve the puzzle."},"themes":{"description":"Tactical themes labeled on this puzzle.","type":"array","items":{"type":"string"}},"initialPly":{"description":"Ply count at puzzle start position.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","rating","solution"],"additionalProperties":{},"description":"Puzzle metadata and solution."}},"required":["game","puzzle"],"additionalProperties":{},"description":"Daily puzzle response."}}}},"402":{"description":"Payment Required"}}}},"/api/user":{"post":{"operationId":"user","summary":"Lichess user profile snapshot: ratings per perf, country, title, online status, counts.","tags":["User"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","minLength":2,"maxLength":30,"pattern":"^[A-Za-z0-9_-]+$","description":"Lichess username (case-insensitive)."}},"required":["username"],"description":"Lichess user profile lookup."}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Lowercase Lichess user id."},"username":{"type":"string","description":"Display username."},"title":{"description":"FIDE title (GM, IM, FM, ...), if any.","type":"string"},"online":{"description":"Whether the user is online now.","type":"boolean"},"perfs":{"description":"Per-variant performance objects keyed by perf name (bullet, blitz, rapid, classical, puzzle, …).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"games":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total games played."},"rating":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Current rating."},"rd":{"description":"Rating deviation.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"prog":{"description":"Rating progression (last 12 games).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"prov":{"description":"Whether the rating is provisional.","type":"boolean"}},"required":["games","rating"],"additionalProperties":{}}},"profile":{"description":"Free-form profile fields set by the user.","type":"object","properties":{"flag":{"description":"ISO 3166-1 alpha-2 country code.","type":"string"},"bio":{"description":"User biography.","type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"links":{"description":"User-provided links.","type":"string"}},"additionalProperties":{}},"createdAt":{"description":"Account creation timestamp (ms epoch).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"seenAt":{"description":"Last activity timestamp (ms epoch).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"playTime":{"description":"Cumulative play time.","type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total seconds played on Lichess."},"tv":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Seconds streamed on Lichess TV."}},"required":["total","tv"],"additionalProperties":false},"count":{"description":"Game count breakdown.","type":"object","properties":{"all":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total games."},"rated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rated games."},"win":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Wins."},"loss":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Losses."},"draw":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Draws."},"bookmark":{"description":"Bookmarked games.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"import":{"description":"Imported games.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["all","rated","win","loss","draw"],"additionalProperties":{}},"url":{"description":"Lichess profile URL.","type":"string"},"patron":{"description":"Whether the user is a Lichess patron.","type":"boolean"},"flair":{"description":"User flair emoji slug.","type":"string"}},"required":["id","username"],"additionalProperties":{},"description":"Lichess user profile snapshot."}}}},"402":{"description":"Payment Required"}}}},"/api/masters":{"post":{"operationId":"masters","summary":"Masters opening explorer for a position. Returns top moves, win/draw/loss rates, and recent top master games from the Lichess masters database.","tags":["Masters"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fen":{"type":"string","minLength":15,"maxLength":100,"description":"Standard FEN position string, e.g. 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'"},"play":{"description":"Comma-separated UCI move sequence to apply to the FEN before lookup (e.g. 'e2e4,e7e5').","type":"string","maxLength":500},"since":{"description":"Include games from this year onward.","type":"integer","minimum":1500,"maximum":2100},"until":{"description":"Include games up to this year.","type":"integer","minimum":1500,"maximum":2100},"moves":{"description":"Max number of top moves to return. Default 12.","type":"integer","minimum":1,"maximum":50},"topGames":{"description":"Number of recent top games to include. Default 4.","type":"integer","minimum":0,"maximum":15}},"required":["fen"],"description":"Masters opening explorer request: FEN plus optional filters and play sequence."}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"white":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total white wins at this position."},"draws":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total draws at this position."},"black":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total black wins at this position."},"moves":{"type":"array","items":{"type":"object","properties":{"uci":{"type":"string","description":"UCI move string."},"san":{"type":"string","description":"SAN move string."},"white":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Games won by white from this move."},"draws":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Drawn games from this move."},"black":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Games won by black from this move."},"averageRating":{"description":"Average rating of players who played this move.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"opening":{"description":"ECO opening classification for this move, when recognized.","anyOf":[{"type":"object","properties":{"eco":{"type":"string","description":"ECO opening code."},"name":{"type":"string","description":"Opening name."}},"required":["eco","name"],"additionalProperties":{}},{"type":"null"}]},"game":{"description":"Representative game for this move, if available.","anyOf":[{"type":"object","properties":{"uci":{"type":"string","description":"UCI move played in this game."},"id":{"type":"string","description":"Lichess game id."},"winner":{"anyOf":[{"type":"string","enum":["white","black"]},{"type":"null"}],"description":"Winner, or null for a draw."},"white":{"type":"object","properties":{"name":{"type":"string","description":"Player name."},"rating":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Player rating."}},"required":["name","rating"],"additionalProperties":false,"description":"White player."},"black":{"type":"object","properties":{"name":{"type":"string","description":"Player name."},"rating":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Player rating."}},"required":["name","rating"],"additionalProperties":false,"description":"Black player."},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Year the game was played."},"month":{"description":"Month string (YYYY-MM).","type":"string"}},"required":["uci","id","winner","white","black","year"],"additionalProperties":{}},{"type":"null"}]}},"required":["uci","san","white","draws","black"],"additionalProperties":{}},"description":"Top moves ordered by frequency."},"topGames":{"description":"Recent top master games at this position.","type":"array","items":{"type":"object","properties":{"uci":{"type":"string","description":"UCI move played in this game."},"id":{"type":"string","description":"Lichess game id."},"winner":{"anyOf":[{"type":"string","enum":["white","black"]},{"type":"null"}],"description":"Winner, or null for a draw."},"white":{"type":"object","properties":{"name":{"type":"string","description":"Player name."},"rating":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Player rating."}},"required":["name","rating"],"additionalProperties":false,"description":"White player."},"black":{"type":"object","properties":{"name":{"type":"string","description":"Player name."},"rating":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Player rating."}},"required":["name","rating"],"additionalProperties":false,"description":"Black player."},"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Year the game was played."},"month":{"description":"Month string (YYYY-MM).","type":"string"}},"required":["uci","id","winner","white","black","year"],"additionalProperties":{}}},"opening":{"description":"ECO opening classification for the position, when recognized.","anyOf":[{"type":"object","properties":{"eco":{"type":"string","description":"ECO opening code."},"name":{"type":"string","description":"Opening name."}},"required":["eco","name"],"additionalProperties":{}},{"type":"null"}]}},"required":["white","draws","black","moves"],"additionalProperties":{},"description":"Masters database aggregate stats for the position."}}}},"402":{"description":"Payment Required"}}}}}}