Built for agents, not just for people

Everything from discovery to payment is an HTTP call. The only step that needs a human is the one that needs a credit card, and the API hands you the link for it.

The loop

Step	Call	What comes back
Discover	`GET /llms.txt`, `GET /openapi.json`	Auth, endpoints, cost annotations in under 800 tokens
Try	`POST /v1/eval` with no key	A real evaluation (depth ≤ 10) plus the signup call to make next
Sign up	`POST /v1/signup {"email", "agent"}`	A live key on the free plan, immediately
Budget	`GET /v1/price`, `X-Quota-Remaining`	Units for any request before you send it; what is left after
Hit a limit	any call → `402`	`next_action`, plan options, and a checkout URL for your human
Keep going	same key	Limits update within 60 s of payment; nothing to reconfigure

 Errors tell you what to do
 Every error is RFC 9457 problem+json with a next_action you can branch on:
  next_action Status Do this
  fix_request 400 Read detail; the request will never succeed as sent
 retry_after 429, 503 Wait Retry-After seconds, then retry with the same Idempotency-Key
 sign_up 401, 402, 429 (keyless) Call the signup object in the body
 upgrade 402 Show checkout.url to your operator, or pick a smaller depth
 raise_budget 402 PATCH /v1/keys/{id} if you hold the keys scope, otherwise ask
 verify_email 403 The account needs its claim email clicked
 contact 403, 501 Surface the message; a person has to act
 
 
 HTTP/1.1 402 Payment Required
Content-Type: application/problem+json

{
  "type": "https://stockfishapi.com/errors/quota_exceeded",
  "title": "Daily quota exceeded",
  "status": 402,
  "next_action": "upgrade",
  "retry_after": 31250,
  "plans": [{ "plan": "hobby", "price_usd_month": 9, "included_units": 100000, "max_depth": 22 }],
  "checkout": { "method": "POST", "url": "https://stockfishapi.com/v1/billing/checkout", "body": { "plan": "hobby" } }
}
 Scoped keys for sub-tasks
 The signup key carries the keys scope, so an agent can mint narrower keys for the work it delegates: POST /v1/keys {"scopes": ["eval"], "budget_units": 500}. A sub-agent that leaks its key can spend at most 500 units and cannot touch billing.
 MCP
 The MCP endpoint at https://stockfishapi.com/mcp supports Streamable HTTP with evaluate_position, best_move, legal_moves, and validate_position. Configure your API key as a Bearer token, or use the keyless trial. OAuth is not supported.
 Retry and backoff
  Honour Retry-After; it is exact, not a guess.
 Send an Idempotency-Key on POSTs you may retry.
 Do not raise depth to "get a better answer" without checking GET /v1/price; cost grows 1.6× per ply.
 Prefer bestmove when you only need a move; it is half the price of eval.

next_action	Status	Do this
`fix_request`	400	Read `detail`; the request will never succeed as sent
`retry_after`	429, 503	Wait `Retry-After` seconds, then retry with the same `Idempotency-Key`
`sign_up`	401, 402, 429 (keyless)	Call the `signup` object in the body
`upgrade`	402	Show `checkout.url` to your operator, or pick a smaller depth
`raise_budget`	402	`PATCH /v1/keys/{id}` if you hold the `keys` scope, otherwise ask
`verify_email`	403	The account needs its claim email clicked
`contact`	403, 501	Surface the message; a person has to act