llms.txt Chess Data API

Chess Puzzles

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

3,000,000 puzzles available
/puzzles supports API key or x402
x402 price $0.01 per puzzle

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

Access Modes

  • API key mode: use GET /puzzles with either key header.
  • x402 mode: use GET /puzzles and pay a dynamic total based on count × $0.01 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.

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 -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"

Tip: /puzzles accepts either an API key or x402 payment. The price is calculated dynamically from the requested puzzle count.