Chess Puzzles API

Base Endpoints

GET /puzzles (API key or x402 payment)

x-api-key: your-key Authorization: Bearer your-key x-payment: signed-payment payment-signature: signed-payment

API key mode: use GET /puzzles with either key header.
x402 mode: use GET /puzzles and pay a dynamic total based on count × $0.005 per puzzle.
Supported networks: Base and Celo.
Supported stablecoins: USDC, USDT, USDm.
Each puzzle object includes a cost field (USD per puzzle unit).
Clients can send API key on /puzzles to skip payment.

The FEN is the position before the opponent's move.
moves[0] is the opponent's move. Present the position to the player after applying moves[0] to the FEN.
moves[1] is the start of the solution (the player's first move).
All player moves are "only moves": any other move would considerably worsen the player's position.
Exception: mates in one can have several solutions. Any move that checkmates wins the puzzle.

curl -H "x-api-key: your-key"     "https://api.chesspuzzles.xyz/puzzles?count=5"

curl -H "x-payment: <signed-payment>"     "https://api.chesspuzzles.xyz/puzzles?count=5"

curl -H "x-api-key: your-key"     "https://api.chesspuzzles.xyz/puzzles?id=00sHx"

curl -H "x-api-key: your-key"     "https://api.chesspuzzles.xyz/puzzles?count=10&rating=1400-1800&themes=["fork","middlegame"]&themesType=ANY"

GET /themes (public, no auth) returns every puzzle theme as { key, name, description }. Use key values in the themes query parameter.

74 themes available.