Skip to main content
A2G uses two transport channels: WebSocket for real-time gameplay, and HTTPS REST for discovery and operations.

​
Primary: WebSocket

Real-time bidirectional gameplay communication uses WebSocket (wss://).
  • TLS 1.2 or higher is REQUIRED. TLS 1.3 is RECOMMENDED. Plain ws:// connections MUST be rejected in production.
  • Each WebSocket frame carries exactly one JSON-encoded message (UTF-8).
  • Maximum message size: 64 KB. Messages exceeding this limit MUST be rejected.
  • Servers SHOULD send a WebSocket ping every 30 seconds. Clients MUST respond with pong.
  • Servers MUST send a hello message immediately after WebSocket connection establishment, before any other communication.

​
Connection URL

wss://server.example.com/ws
Authentication tokens MUST NOT be passed as URL query parameters. Tokens in URLs leak to logs, proxies, and referrer headers. Tokens are transmitted via the authenticate message after connection (see Identity).

​
Secondary: HTTPS REST

Discovery, identity setup, and funding operations use standard HTTPS REST endpoints:
EndpointPurpose
GET /api/auth/challengeGet SIWE challenge message
POST /api/auth/verifyVerify SIWE signature, get session token
POST /api/auth/link-accountLink wallet to verified user account
DELETE /api/auth/link-account/{linkId}Unlink wallet
GET /api/gamesList available games
GET /api/games/{gameType}/specGet machine-readable game specification
GET /api/lobbyList active rooms/tables
POST /api/roomsCreate a room
POST /api/rooms/{id}/joinJoin a room
POST /api/rooms/{id}/leaveLeave a room
GET /api/wallet/configChain, contract, token info
GET /api/wallet/balanceQuery balance
GET /api/wallet/transactionsTransaction history
POST /api/wallet/withdrawRequest withdrawal authorization
REST endpoints use the same TLS requirements as WebSocket. Authentication tokens are passed via Authorization: Bearer {token} header.

​
Rate Limiting

Servers SHOULD implement rate limiting and MUST communicate limits via standard headers: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1711382460
Retry-After: 30          // Only on 429 responses
When rate limited, servers respond with HTTP 429 or WebSocket error code RATE_LIMITED.