# stockfishapi.com

> Hosted Stockfish 17 chess engine over HTTPS. Send a FEN, get an evaluation, best move and principal variations. Built for developers and AI agents.

## Auth
Bearer API key: `Authorization: Bearer sk_live_...`. No key needed for a keyless trial (depth <= 10, 10 requests/hour/IP).

## Sign up (no browser needed)
POST https://stockfishapi.com/v1/signup  {"email":"you@example.com","agent":"<your runtime>"}
Returns a live key immediately on the Free plan: depth <= 14, 2,000 units/day, 5 rps burst.

## Core endpoints
- POST /v1/eval      {"fen":"...","depth":14,"multipv":3}  -> eval, bestmove, pvs, cost_units
- POST /v1/bestmove  {"fen":"...","depth":12}              -> bestmove (cheapest call)
- GET  /v1/price?endpoint=eval&depth=14&multipv=3          -> units and USD before you call
- GET  /v1/usage                                           -> remaining quota and budget
- POST /v1/legal-moves, POST /v1/validate                  -> free utilities
- GET  /v1/engines                                         -> versions (default: stockfish-17 = "latest") and option schema

## Engine options (all optional, sensible defaults)
"engine": "latest" | "stockfish-17" | "stockfish-17"   pin a version; deprecated versions send Deprecation/Sunset headers
"options": {"elo": 1800}                                   play at a rating; also hash_mb, chess960, show_wdl, skill_level
"path": "auto" | "wasm" | "native"                         where it runs; leave on auto
POST /v1/analyze accepts PGN, POST /v1/batch accepts fens. Both return 202 with a job id; poll GET /v1/jobs/{id}, download /v1/jobs/{id}/result, or stream /v1/jobs/{id}/events. Jobs allow 50 positions, depth 14, and 3 PVs. MCP is available at /mcp.

## Cost and limits
Every response carries X-Cost-Units, X-RateLimit-Remaining, X-Quota-Remaining. Cached positions cost 0.
1 unit = 500k engine nodes, quoted up front and enforced as a hard cap (go depth D nodes N). Depth 14 = 2 units, depth 20 = 22, depth 30 = 2,418.
Launch plan: Free $0 (depth 14, 2k units/day). Paid subscriptions are not enabled.

## Errors
RFC 9457 problem+json. Branch on `next_action`: fix_request | retry_after | upgrade | raise_budget | verify_email | sign_up.
A 402 includes plan options and `checkout`: POST /v1/billing/checkout {"plan":"hobby"} returns a URL a human opens once; the key stays the same.

## More
- OpenAPI: https://stockfishapi.com/openapi.json
- Agent guide: https://stockfishapi.com/agents