API pública / de bots

Envie Authorization: Bearer kirichess_pat_… em toda requisição. Os escopos são exatamente dois. Um token nunca carrega permissões de admin nem de 2FA, mesmo que a conta carregue. Até 10 tokens podem estar ativos ao mesmo tempo. Um token dura 90 dias, a menos que você escolha outra vida entre 1 e 365 dias, e você pode revogá-lo antes no cartão Tokens de API da sua página de perfil.

Depois de kirichess_pat_ vêm 43 caracteres do alfabeto base64 seguro para URL (A–Z, a–z, 0–9, hífen, sublinhado) e em seguida 6 caracteres de soma de verificação. A soma é o CRC-32 (IEEE) desses 43 caracteres, escrito como 6 dígitos em base 62 no alfabeto 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz, preenchido à esquerda com zeros. Um scanner de segredos pode rejeitar uma string que falhe nessa verificação sem chamar este servidor.

• read, identidade, suas partidas, reproduções terminadas, seus desafios abertos, ratings do grupo de bots, solicitações de bots.
• play, criar partidas e desafios não ranqueados, jogar lances e desistir, e entrar no pareamento do grupo de bots pelo hub. Play implica read no momento da emissão.

A sua engine roda no processo que chama esta API. Origens de navegador que não sejam este site continuam bloqueadas; o CORS não é ampliado para esta API.

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

POST /api/v1/games cria apenas uma partida solo, os dois lugares são você, para exercitar a engine de ponta a ponta. Um opponentId que aponte para outra pessoa é recusado: o jogo pareado passa sempre por POST /api/v1/challenges ou pelo grupo de bots. A medição ranqueada é opcional: conecte-se ao hub de partidas com o mesmo token e chame JoinQueue com um preset oficial (bounty1, burn1, steal1, steal2, burn2, steal3). Isso é remapeado para bot:{preset} e nunca se mistura com o Glicko humano.

O grupo de bots é uma cortesia para autores de bots honestos, não uma barreira técnica: um script que faz login com a senha de uma conta é indistinguível de um navegador na fila e acaba no grupo humano. Jogar no grupo humano a partir de um script é contra as regras, seja qual for a credencial usada para autenticá-lo.

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}'

Conecte-se a wss://api.kirichess.com/hubs/game. Um bot se autentica do mesmo jeito que em qualquer outro lugar desta API: envie Authorization: Bearer kirichess_pat_… na solicitação de conexão. O site próprio coloca um JWT de sessão de curta duração na query access_token, porque um navegador não consegue definir um cabeçalho num handshake WebSocket. O servidor ainda aceita um token kirichess_pat_… nessa query. Não coloque um lá: ele fica registrado no log de proxy da Fly, no log de requisições da Cloudflare e na URL da requisição capturada pelo Sentry.

Métodos de jogador: JoinQueue, SubmitMove, Resign, OfferDraw, RespondDraw e LeaveQueue. Eventos: MatchFound, MovePlayed, GameEnded, DrawOffered, DrawDeclined, OpponentDisconnected e OpponentReconnected. WatchChallenge e UnwatchChallenge inscrevem esta conexão num desafio que você criou; OfferRematch e AcceptRematch continuam uma partida encerrada. JoinAsSpectator continua anônimo. Um ciclo que funciona é conectar, JoinQueue, esperar MatchFound e então JoinGame(gameId) para obter a posição atual e se inscrever nos eventos dessa partida antes de chamar SubmitMove ou reagir a MovePlayed; sem JoinGame, nenhum evento MovePlayed chega. Lances de uma partida pareada pelo hub também podem ser enviados com POST /api/v1/games/{id}/moves em vez do hub, se isso for mais fácil para o seu cliente.