API pública / de bots

Envía Authorization: Bearer kirichess_pat_… en cada petición. Los ámbitos son exactamente dos. Un token nunca lleva permisos de administrador ni de 2FA, aunque la cuenta sí los tenga. Puede haber hasta 10 tokens activos a la vez. Un token dura 90 días salvo que elijas otra vida entre 1 y 365 días, y puedes revocarlo antes desde la tarjeta Tokens de API en tu página de perfil.

Después de kirichess_pat_ van 43 caracteres del alfabeto base64 seguro para URL (A–Z, a–z, 0–9, guion, guion bajo) y luego 6 caracteres de suma de comprobación. La suma es el CRC-32 (IEEE) de esos 43 caracteres, escrito como 6 dígitos base62 en el alfabeto 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz, rellenado a la izquierda con ceros. Un escáner de secretos puede rechazar una cadena que no supere esa comprobación sin llamar a este servidor.

• read, identidad, tus partidas, reproducciones terminadas, tus desafíos abiertos, puntuaciones del grupo de bots, solicitudes de bots.
• play, crear partidas y desafíos no puntuables, mover y abandonar, y entrar en el emparejamiento del grupo de bots por el hub. Play implica read en el momento de emitirlo.

Tu motor corre en el proceso que llama a esta API. Los orígenes de navegador distintos de este sitio siguen bloqueados; CORS no se amplía para esta API.

curl https://api.kirichess.com/api/v1/account \
  -H "Authorization: Bearer $KIRICHESS_API_TOKEN"

POST /api/v1/games crea solo una partida en solitario, ambos asientos eres tú, para ejercitar el motor de punta a punta. Rechaza un opponentId que apunte a otra persona: el juego emparejado pasa siempre por POST /api/v1/challenges o por el grupo de bots. La medición puntuable es opcional: conéctate al hub de partidas con el mismo token y haz JoinQueue con un preajuste oficial (bounty1, burn1, steal1, steal2, burn2, steal3). Eso se reasigna a bot:{preset} y nunca se mezcla con el Glicko humano.

El grupo de bots es una cortesía para autores de bots honestos, no una barrera técnica: un script que inicia sesión con la contraseña de una cuenta es indistinguible de un navegador en la cola y termina en el grupo humano. Jugar en el grupo humano desde un script va contra las reglas, sea cual sea la credencial con la que se autentique.

curl -X POST https://api.kirichess.com/api/v1/games \
  -H "Authorization: Bearer $KIRICHESS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preset":"bounty1","opponentId":null,"rated":false}'

Conéctate a wss://api.kirichess.com/hubs/game. Un bot se autentica igual que en el resto de esta API: envía Authorization: Bearer kirichess_pat_… en la solicitud de conexión. El sitio propio pone un JWT de sesión de vida corta en la query access_token, porque un navegador no puede poner una cabecera en un handshake de WebSocket. El servidor sigue aceptando un token kirichess_pat_… en esa query. No pongas uno ahí: queda registrado en el log del proxy de Fly, en el log de peticiones de Cloudflare y en la URL de la petición que captura Sentry.

Métodos de jugador: JoinQueue, SubmitMove, Resign, OfferDraw, RespondDraw y LeaveQueue. Eventos: MatchFound, MovePlayed, GameEnded, DrawOffered, DrawDeclined, OpponentDisconnected y OpponentReconnected. WatchChallenge y UnwatchChallenge suscriben esta conexión a un desafío que tú creaste; OfferRematch y AcceptRematch continúan una partida terminada. JoinAsSpectator sigue siendo anónimo. Un bucle que funciona es conectar, JoinQueue, esperar MatchFound y luego JoinGame(gameId) para obtener la posición actual y suscribirte a los eventos de esa partida antes de llamar a SubmitMove o reaccionar a MovePlayed; si omites JoinGame, no llega ningún evento MovePlayed. Las jugadas de una partida emparejada por el hub también pueden enviarse con POST /api/v1/games/{id}/moves en lugar del hub, si eso es más fácil para tu cliente.