Chess Data API

Chess Puzzles

Query puzzles by ID, random count, rating range, themes, and player-move depth. Access with API keys or pay-per-use over x402 on Celo stablecoins.

Base Endpoints

GET /puzzles (API key required)

GET /puzzles/x402 (API key or x402 payment)

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

Access Modes

  • API key mode: use GET /puzzles for existing key-based flows.
  • x402 mode: use GET /puzzles/x402 and pay a dynamic total based on count × X402_PRICE_USD_PER_PUZZLE.
  • Supported stablecoins: USDC, USDT, USDm.
  • Each puzzle object includes a cost field (USD per puzzle unit).
  • Clients can send API key on /puzzles/x402 to skip payment.

Query Parameters

  • id: fetch one puzzle by ID (overrides filters)
  • count: number of random puzzles to return (1-100)
  • rating: exact value or range (example: 1500, 1200-1800)
  • themes: JSON array (example: ["fork","pin"])
  • themesType: ANY or ALL when multiple themes are sent
  • playerMoves: exact value or range (example: 2, 2-4)

Example Requests

curl -H "x-api-key: your-key" 	"https://api.chesspuzzles.xyz/puzzles?count=5"
curl "https://api.chesspuzzles.xyz/puzzles/x402?count=5"
curl -H "x-payment: <signed-payment>" 	"https://api.chesspuzzles.xyz/puzzles/x402?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"

Tip: /puzzles keeps strict API-key auth. /puzzles/x402 calculates payment dynamically from requested puzzle count.