Game APIs

Public HTTP APIs use POST except health. Send Content-Type: application/json and token: YOUR_TOKEN to the approved app's base URL. See Authentication for errors and retries. IDs, URLs, players and amounts below are examples.

Game catalog

POST /api/v1/gamelist

Send {} with no parameters. The response message is a JSON string; parse it once more. The table describes the decoded object.

{"success":true,"message":"{\"list\":[{\"game_code\":\"baccarat\",\"name\":\"Baccarat\",\"game_type\":\"table\",\"thumb_url\":\"https://games.example.invalid/thumb/baccarat.png\",\"priority\":1,\"status\":1,\"version\":\"1\"}],\"timestamp\":1792000000}"}

The server does not guarantee sorting. The catalog does not return game_id, room_mode or hot_priority. Default rooms are server-managed; do not rebuild game URLs from directory names.

Launch a game

POST /api/v1/user/launch_url

Obtain an entry for a player authenticated on your site. Call from your server; do not let the browser impersonate arbitrary players.

{"user":"test-player-001","name":"Test player","avatar":"default","country_code":"CN","game":"baccarat","theme":"0"}

{
  "success":true,
  "user_key":"WALLET_SESSION_KEY",
  "game":"baccarat",
  "launch_url":"https://games.example.invalid/?session=OPAQUE_SESSION&game=baccarat&theme=0&serverUrl=wss%3A%2F%2Fgames.example.invalid%2Fws"
}

Identical user values are independent across partners. Obtaining a URL does not mean game login or wallet opening has completed. Repeated calls may issue another entry or resume the current game; read response game. Never construct, publicly expose or cache launch_url long-term. lobby_url currently does not change behavior. For iframe return, see Browser integration.

Typical failure messages: invalid user code (invalid format), invalid country_code, invalid user_code (player creation failure, possibly an invalid requested game), invalid game_code, machine unavailable (stale location), default room unavailable and profile update failed. These can arrive as HTTP 200 with success=false. Do not retry indefinitely.

Player status

POST /api/v1/user/status

Query a player under the current partner. user is required and must exactly match the launch value.

{"user":"test-player-001"}

{"success":true,"status":"offline"}

{
  "success":true,
  "game_code":"baccarat",
  "status":"online",
  "session":"OPAQUE_SESSION",
  "session_timestamp":1792000000,
  "session_time":60,
  "login_timestamp":1792000010,
  "login_time":50,
  "balance":10000000,
  "open_status":2
}

Missing user returns success=false and message="user code empty". Without a runtime record, only success and status are returned. Do not assume optional fields exist.

Request exit

POST /api/v1/user/kick

user is a required string. This requests player exit; it is not synchronous settlement.

{"user":"test-player-001"}

{"success":true,"status":"pending"}

pending means an exit notification was sent; offline means the player is not currently online. Missing user returns user code empty. Neither successful status proves close callback completion. Withdrawals and adjustments must follow your reconciled wallet state. Query status after a timeout rather than assuming exit did not execute.

Avatar catalog

POST /api/v1/avatars

Send {}. This API returns top-level list directly, with no message parsing.

{"success":true,"list":[{"avatar":"default","url":"https://games.example.invalid/avatars/default.png"}]}

Public machine catalog

POST /api/v1/game/tables

Send {} to retrieve valid snapshots. message is a JSON string. Only games reporting machines appear; an empty array does not mean all games are unavailable.

{"success":true,"message":"{\"tables\":[{\"server_id\":101,\"room_id\":1,\"game_id\":100,\"table_id\":1,\"game_code\":\"example-game\",\"occupied\":false,\"players\":0,\"capacity\":1,\"jackpot\":\"100000\"}]}"}

Snapshots older than 15 seconds are omitted. The catalog can change before launch. If launch returns machine unavailable, refresh and select again.

Game activity

POST /api/v1/game/activity

For online counts and win display, not transaction lookup. cursor is an optional string, initially empty. Send the previous response cursor unchanged; do not parse or construct it.

{"cursor":""}

{"success":true,"message":"{\"cursor\":\"EPOCH:42\",\"reset\":true,\"games\":[{\"game_code\":\"baccarat\",\"online\":12,\"stale\":false}],\"wins\":[{\"event_id\":\"101:example-event\",\"game_code\":\"baccarat\",\"nickname\":\"Example player\",\"avatar\":\"default\",\"country_code\":\"CN\",\"amount\":\"1000\",\"amount_type\":\"net_win\",\"occurred_at\":1792000000}]}"}

Human activity is partner-filtered; bot activity is shared. Initial/reset results begin with at most the latest 20 global sequence entries and may contain fewer after filtering. Memory retains up to 2000 entries over roughly 10 minutes; historical replay is not guaranteed. Continue with returned cursors. There is no limit or historical-time-range query. Never use this feed for reconciliation.

Health

GET /api/v1/health

No request body or token. This checks only HTTP entry readiness.

{"status":"ok","pending":0}

Successful health checks do not prove database, all game instances, WebSocket or partner callback health. Public routes do not expose deposits, balance modification or historical ledger queries.