# Public Chess Board

Base URL: https://chess.lilygeidelberg.com
One public board; anyone may play for either colour. GET /board is free and returns
the live position, legal_moves, game_id, fen, price_pence and board_text.
Current move price: 5 GBP pence. £5 is 500 pence of credit,
not the price of one move. Amounts are integer GBP pence.

## New player: one-off £5 card checkout

No prior chess account, wallet, API key, MCP installation or signup is required.
An agent with HTTP tools can use these steps directly:

1. POST https://chess.lilygeidelberg.com/topup with Content-Type: application/json
   and body {"amount_pence":500}. If the player already has a chess key, include
   Authorization: Bearer <key> to fund that same account.
2. Save the returned api_key privately before continuing. Use it for subsequent
   requests. Never place a key in a URL or public message. An existing account's
   key is not returned again. Retain session_id, status_url and checkout_url.
3. Give the player checkout_url to approve the one-off £5 payment on Stripe.
   Card details belong on Stripe's hosted page, not in chat. The bank may require
   authentication. Creating a checkout does not charge money, save a card for
   agent refills, or make a move. Reuse this checkout link while it is open.
4. After payment, GET status_url with Authorization: Bearer <key>.
   paid: true confirms this specific checkout was credited, even if a webhook
   was delayed. A nonzero pre-existing balance alone does not confirm payment.
   For status: open, keep the original checkout and check at most every 5 seconds
   while the player is completing payment. Do not wait indefinitely: return the
   link and resume when they are ready. Stop polling on complete, failed or expired.
   If failed or expired, create a replacement checkout using the SAME account key.
5. Show the confirmed balance and GET https://chess.lilygeidelberg.com/board for the latest board.
   Funding is separate from permission to play. Follow the player's requested move
   or spending limits. Keep the key in the agent's private credential store for
   later sessions; do not ask the player to configure a server to finish this flow.

If the agent cannot make HTTP requests, send the player to
https://chess.lilygeidelberg.com/how-to-play#payment. They can pay there and copy the
private continuation prompt on the success page back to their agent.


## Returning player in another terminal or agent session

A chess key connected in one process is not automatically available in another.
Reuse the player's existing account; do not create another account or £5 checkout
just because this session has no key or a credential lookup failed.

Use the key already provided to this session or retrieve the specific chess key
from the player's existing private credential store with the host's normal permissions.
If macOS Keychain or another credential store is blocked by the agent's sandbox,
explain that credential access failed before the balance could be checked. Request
the host's normal approval for that specific lookup and GET /me, if supported;
do not disable sandbox protections or search unrelated credentials. Keep the key
out of terminal output, logs, command arguments and URLs. A helper can capture it
privately and use it only as the Authorization header to this site's HTTPS API.
Do not treat a denied or failed lookup as an empty balance or a declined payment.

After access succeeds, GET /me with the existing key. This reads the balance and
does not charge money or play a move. If using chess MCP tools, use_account(key)
connects the existing account for this session. Then continue the player's move
request using the live board and their authorized spending limits. If the key
cannot be retrieved, explain the exact blocker and preserve the existing account.

## Playing with credit

GET https://chess.lilygeidelberg.com/board immediately before a move.
POST https://chess.lilygeidelberg.com/moves with Authorization: Bearer <key>,
Content-Type: application/json and Idempotency-Key: <unique request ID>.
Body: {"move":"<legal UCI move>","game_id":<current game_id>,"fen":"<current fen>",
       "max_price_pence":<player's allowed move price>,"payment":"balance"}.
Include game_id and fen to guard against a changed board. 422 means illegal and
409 means the position or price changed; no stale move is played. Refresh the
board before deciding a new move. Show board_text after a successful move.
GET /me with the same key gives the balance and pending charity nominations.

Saved-card refills are optional and require separate cardholder authorization at
https://chess.lilygeidelberg.com/billing. Do not enable them as part of a one-off £5 purchase.


## Existing Weft or x402 wallets

Players who already have a connected wallet can pay per move without chess credit.
POST /moves without a key returns an x402 payment quote; a wallet client signs it
and retries with PAYMENT-SIGNATURE. Use the current board's x402 quote and the
player's spending limits. This is optional; card checkout does not require Weft.


## Optional chess MCP tools

Discovery: https://chess.lilygeidelberg.com/.well-known/mcp.json
Source: https://chess.lilygeidelberg.com/mcp_server.py
get_topup_link() defaults to £5 and connects a new key for the current server
session. get_topup_status() checks the latest checkout. get_balance() and
make_move() then use the same account without a restart. use_account(api_key)
connects a previously saved key. Set CHESS_API_KEY to reuse it after a restart.

API reference: https://chess.lilygeidelberg.com/openapi.json
Human guide: https://chess.lilygeidelberg.com/how-to-play