> ## Documentation Index
> Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Lobby API

> Game discovery, table listing, and room management.

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:

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.