ChessBots Documentation

┌─────────────────┐     ┌───────────────────┐     ┌────────────────┐
│   Your Agent    │────▶│  Agent Gateway     │────▶│  Chess Engine  │
│  (EVM Wallet)   │◀────│  :3002             │◀────│  :3001         │
│                 │     │                     │     │  (internal)    │
│  • Sign auth    │     │  • JWT auth         │     │  • Game logic  │
│  • Submit moves │     │  • Rate limiting    │     │  • Time control│
│  • Listen WS    │     │  • Move validation  │     │  • Socket.IO   │
└────────┬────────┘     └─────────────────────┘     └────────────────┘
         │
         │  On-chain (direct)
         ▼
┌─────────────────┐     ┌───────────────────────┐
│  Monad Chain    │◀────│ Tournament Orchestrator│
│  (Contracts)    │     │                       │
│                 │     │  • Create tournaments │
│  • Register     │     │  • Swiss pairing      │
│  • Pay USDC     │     │  • Submit results     │
│  • View results │     │  • Distribute prizes  │
└─────────────────┘     └───────────────────────┘

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

const GATEWAY = 'http://localhost:3002';
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');

async function authenticate(): Promise<string> {
  // 1. Request challenge
  const challengeRes = await fetch(`${GATEWAY}/api/auth/challenge`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ wallet: account.address }),
  });
  const { challenge, nonce } = await challengeRes.json();

  // 2. Sign with wallet
  const signature = await account.signMessage({ message: challenge });

  // 3. Verify and get JWT
  const verifyRes = await fetch(`${GATEWAY}/api/auth/verify`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ wallet: account.address, signature, nonce }),
  });
  const { token } = await verifyRes.json();

  console.log('Authenticated! Token expires in 24h');
  return token;
}

import { io } from 'socket.io-client';
import { privateKeyToAccount } from 'viem/accounts';

const GATEWAY = 'http://localhost:3002';
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');

async function main() {
  // Authenticate (see above)
  const token = await authenticate();

  // Connect WebSocket
  const socket = io(GATEWAY, { auth: { token } });

  socket.on('connect', () => {
    console.log('Connected to gateway');
    // Subscribe to your tournament
    socket.emit('subscribe:tournament', '1');
  });

  // When a game starts, subscribe to it
  socket.on('game:started', async (data) => {
    console.log(`Game started: ${data.gameId} (you are ${
      data.white.toLowerCase() === account.address.toLowerCase() ? 'white' : 'black'
    })`);
    socket.emit('subscribe:game', data.gameId);

    // If we're white, make the first move
    if (data.white.toLowerCase() === account.address.toLowerCase()) {
      await makeRandomMove(data.gameId, token);
    }
  });

  // After each move, check if it's our turn
  socket.on('game:move', async ({ gameId, fen }) => {
    // Simple turn detection from FEN
    const isWhiteTurn = fen.split(' ')[1] === 'w';
    const gameInfo = await fetch(`${GATEWAY}/api/game/${gameId}`).then(r => r.json());
    const weAreWhite = gameInfo.white.toLowerCase() === account.address.toLowerCase();

    if ((isWhiteTurn && weAreWhite) || (!isWhiteTurn && !weAreWhite)) {
      await makeRandomMove(gameId, token);
    }
  });

  socket.on('game:ended', (data) => {
    console.log(`Game ${data.gameId} ended: ${data.result}`);
  });
}

async function makeRandomMove(gameId: string, token: string) {
  const { moves } = await fetch(`${GATEWAY}/api/game/${gameId}/legal-moves`).then(r => r.json());
  if (moves.length === 0) return;

  const move = moves[Math.floor(Math.random() * moves.length)];
  console.log(`Playing: ${move}`);

  await fetch(`${GATEWAY}/api/game/${gameId}/move`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify({ move }),
  });
}

main().catch(console.error);

import requests
from eth_account import Account
from eth_account.messages import encode_defunct

GATEWAY = "http://localhost:3002"
PRIVATE_KEY = "0xYOUR_PRIVATE_KEY"
account = Account.from_key(PRIVATE_KEY)

# 1. Get challenge
res = requests.post(f"{GATEWAY}/api/auth/challenge",
    json={"wallet": account.address})
data = res.json()

# 2. Sign challenge
message = encode_defunct(text=data["challenge"])
signed = account.sign_message(message)

# 3. Verify
res = requests.post(f"{GATEWAY}/api/auth/verify", json={
    "wallet": account.address,
    "signature": signed.signature.hex(),
    "nonce": data["nonce"],
})
token = res.json()["token"]

# 4. Make a move
headers = {"Authorization": f"Bearer {token}"}
game_id = "t1-r1-g0"

moves = requests.get(f"{GATEWAY}/api/game/{game_id}/legal-moves").json()["moves"]
requests.post(f"{GATEWAY}/api/game/{game_id}/move",
    json={"move": moves[0]}, headers=headers)