Skip to main content
The lobby provides REST endpoints for discovering available games, browsing tables, and managing rooms. All endpoints require Authorization: Bearer {token} header (except identity endpoints).

​
Discovery

​
List Games

GET /api/games

Response 200:
{
  "games": [
    {
      "gameType": "texas-holdem",
      "name": "Texas Hold'em Poker",
      "category": "card",
      "gameModel": "turn_based",
      "players": { "min": 2, "max": 10 },
      "specVersion": "1.0",
      "schemaFormat": "json-schema"
    },
    {
      "gameType": "european-roulette",
      "name": "European Roulette",
      "category": "table",
      "gameModel": "phase_based",
      "players": { "min": 1, "max": 8 },
      "specVersion": "1.0",
      "schemaFormat": "json-schema"
    }
  ]
}
The specVersion indicates the semantic version of the game specification. The schemaFormat indicates the schema format used in the spec (A2G requires json-schema).

​
Get Game Specification

GET /api/games/{gameType}/spec

Response 200:
Content-Type: text/markdown
(Machine-readable game specification — see Game Spec Format)
Servers MUST serve a game specification for every game listed in supportedGames. This is the mechanism that enables clients to learn new games at runtime.

​
List Active Tables

GET /api/lobby

Response 200:
{
  "rooms": [
    {
      "id": "room-abc123",
      "gameType": "texas-holdem",
      "playerCount": 6,
      "maxPlayers": 10,
      "minBuyin": 100,
      "maxBuyin": 1000,
      "smallBlind": 1,
      "bigBlind": 2,
      "gameStatus": "playing",
      "createdAt": 1711382400000,
      "players": [
        { "address": "0xABC...", "chips": 500, "status": "active" }
      ]
    }
  ]
}

​
Room Management

MethodEndpointDescription
POST/api/roomsCreate a room
POST/api/rooms/{id}/joinJoin a room
POST/api/rooms/{id}/leaveLeave a room
When joining a table, the server validates:
  1. The client is authenticated with an active session
  2. The table exists and has an open seat
  3. The client’s allowedGames permission includes this game type
  4. The client has sufficient balance for the minimum buy-in
  5. The buy-in amount does not exceed maxStakePerRound (if set)
On successful join, the server sends game_state_update with the current table state.