Games
Game lobbies and their matches: list and open tables, read a match's board, and read a player's record.
A lobby is a smart product in the GAME domain and a match is one of its instances - see
Game Lobbies for the model and what it guarantees. These routes
are the reads a board draws itself from, and the draft routes an operator opens a table with.
Opening a lobby needs the CREATE_GAMES entitlement.
Playing is not here. Every seat, move, claim and bomb is a transaction the player signs against the
lobby contract, sent through POST /api/privy/sign/game-action - see
Contracts and signing. Read the board back with the match route once the
chain event lands.
Lobbies and matches
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /api/games | app key | List game lobbies. |
POST | /api/games | app key + user, entitlement, app access | Open a lobby. Accepts the smart-lobby recipe. |
DELETE | /api/games/{id} | app key + user | Delete a draft lobby. |
GET | /api/games/{id} | app key | One lobby, with the seats of the match being formed. |
PATCH | /api/games/{id} | app key + user | Update a draft lobby. |
GET | /api/games/{id}/matches | app key | The lobby's matches, newest first. |
GET | /api/games/{id}/matches/{matchIndex} | app key | One match: the board, the moves, whose turn, the kitty. |
GET | /api/games/records/{address} | app key | One address's game record: matches played, won, drawn, lost, hosted, and prizes claimed. Every game by default; ?game= for one. |
GET | /api/games/leaderboard | app key | One game's leaderboard (game required): every address that finished a match of that game, ranked by wins, then draws, then fewest losses. limit is 1-100, default 20. |
The record counts every game an address played unless game narrows it to one; the leaderboard
is always per game, so there game is required (tic-tac-toe or connect-four). Tied lines share a rank and the next rank skips. A
leaderboard row carries an address, never a name - resolve names in one batch with
users.batchLookupUsers.
GET /api/games accepts sourceAppId, so an app lists only its own tables. A match row carries
its instanceId; the trophy or match picture is that instance's product image
(GET /api/product-images, entity product_instance).
The trophy preview
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /api/styles/games/preview/{id} | app key | Draw a trophy in a GAME style set from a sample match. The body is { sample }; the answer is the page preview's shape. |
The sample is replayed under the game's rules before anything is drawn, so an illegal move, a bomb
on an empty square, or a match that never ends is a 400 naming it (ILLEGAL_MOVE,
INVALID_SAMPLE, UNFINISHED_MATCH), and a style set from another domain is DOMAIN_MISMATCH.
The SDK wraps the lobby routes as rtClient.games and the preview as
rtClient.gameStyles.generateLivePreview.