Lobby API - A2G Protocol

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

Method	Endpoint	Description
`POST`	`/api/rooms`	Create a room
`POST`	`/api/rooms/{id}/join`	Join a room
`POST`	`/api/rooms/{id}/leave`	Leave a room

When joining a table, the server validates:

The client is authenticated with an active session
The table exists and has an open seat
The client’s allowedGames permission includes this game type
The client has sufficient balance for the minimum buy-in
The buy-in amount does not exceed maxStakePerRound (if set)

On successful join, the server sends game_state_update with the current table state.