Developers
Game server API
On this page
The game server handles wallet sessions, the house games and
Hold'em against the dealer. It runs separately from the static site. Real play is open for its listed games while the server reports ready.
- Server origin
https://api.playtilt.gg- Network
- Elysium, 99901
- Account and house amounts
- 1 USDC = 1,000,000 micro-units
Hold'em amounts- Ante in whole USDC cents; the reserve is 4 × ante, 40,000 micro-units per ante cent
Conventions
- JSON over HTTPS/WSS. POST bodies have a 16 KB limit. A larger body gets HTTP 413
{ok:false,error:"request too large"}; an unreadable one gets 400"bad body". - Authenticated HTTP sends
Authorization: Bearer <token>. House/game amounts are integer micro-units, usually numbers within supported safe bounds; typed consent amounts/nonces/deadlines are decimal strings. - Command responses preserve
{ok,code?,error?,data?}. A rejection may be malformed input, insufficient free funds, a closed admission gate or a pending chain operation. Do not infer success from a connected socket. - A server fault answers HTTP 500 with
{ok:false,error:"Something went wrong; your balance is safe.",requestId}. The text is always the same and never carries internal detail.requestIdis a short code; quote it to support, which can find the matching server log. Over WebSocket the acknowledgement carries the same text without arequestId. - CORS supports content-type/authorization and GET/POST/OPTIONS.
- Custody acknowledgements wait for twelve canonical L2 confirmations. This is a shallow-fork policy, not irreversible bridge finality or a guaranteed response time.
Account host
| Method/path | Auth | Purpose |
|---|---|---|
GET /api/account/health | None | Account host and receipt-sync status |
POST /api/account/wallet/challenge | None | {address} returns the exact sign-in message |
POST /api/account/wallet/login | None | {address,signature,name?} returns token/account on success |
POST /api/account/wallet/link/challenge | Bearer | Challenge for linking a wallet to an existing account |
POST /api/account/wallet/link | Bearer | Verify its personal-message signature |
GET /api/account/me | Bearer | Account, mirrored balance and queued account events |
GET /api/account/vault-balance | Bearer, linked wallet | {ok,chainId,walletTokenBalance,vaultFreeBalance,vaultLockedBalance,unit}; amounts as strings |
Accounts and sessions
Session tokens identify accounts; the linked wallet proves ownership. A guest account is not an authorization to debit USDC. The local account ledger mirrors confirmed linked-wallet receipts; onchain free balance is the authority for funds.
Wallet sign-in
- Request a challenge for your address.
- Sign that exact message with EIP-191 personal-sign.
- Submit address/signature before the five-minute challenge expiry and retain the returned session token.
A wallet sign-in token lasts 7 days from its last use. Using it renews it (the renewal is saved at most once an hour), so a player who keeps playing stays signed in. After 7 days without use it stops working and the player signs in again. House-play session tokens keep the fixed expiry of their approval and are not renewed by use.
Sign-in costs no gas and authorizes no bet, token approval or withdrawal. Each new challenge replaces the previous open challenge for that address.
Account commands
Account changes use authenticated commands. Wallet linking requires its signed challenge/link flow; submitting an unsigned wallet address cannot prove ownership. Account and public routes are rate limited, and operator money commands are rejected from player endpoints.
House-game API
The house-game host exposes health, tables, seeds, commands, account history and settled-round verification. Exact endpoint paths and complete TypeScript shapes are in the repository's API reference under docs/; this page explains the protocol by purpose.
| Purpose | Response/request |
|---|---|
| Health | Enable play only for readiness.testnetPlayReady:true (the field keeps its original name), status ready, correct chain/vault and active table |
| Release | The house-game health reply includes release:{tag,commit}: the release tag and commit hash this server runs, or "unknown" for a value that is not set |
| Open errors | vault.errors in the same reply is {count,oldestAgeMs}: how many vault operations are in an error state and how long the oldest has been (null when none). It no longer lists operation IDs |
| Tables | {tables}; public current views and confirmed history |
| Seeds | {chains,clientSeed}; no private future preimages |
| Command | Bearer-authenticated {cmd,stakeAuthorization?}; returns {ok,code?,error?,data?} |
| Your history | Bearer-authenticated {bets,next}, opaque cursor |
| Verify | Returned round ID identifies a settled {ok,proof,recomputed,error?} |
Tables and seeds
The house table IDs are crash-main, dice-main, flip-main and blackout-main. Overhang and Pinwheel tables (overhang-normal, overhang-hard, pinwheel-steady, pinwheel-wild) are listed in health once their vault tables read as configured. Dice/Flip/Blackout allocate independent wallet/game chains so an unfinished private round is not revealed by another wallet. Always use returned round IDs and current limits; do not construct IDs or assume every displayed stake is admissible.
History and verification
History is a record of accepted bets, not proof of a wallet withdrawal. A settled proof includes commit, index, revealed seed, drand salt, exact input fields and outcome. Blackout also identifies its entropy scheme. Recompute it locally with the fairness specification.
Commands
| Game | Sequence |
|---|---|
| Crash Tower | crash.bet {tableId,stake,autoCashout} with stake consent; crash.cashout {roundId} |
| Dice | dice.reserve {tableId,stake}, then dice.spot {tableId,roundId,stake,direction,targetCents} with consent |
| Blob Flip | flip.reserve {tableId,stake}, then flip.bet {tableId,roundId,stake,call} with consent |
| Blackout | blackout.open {stake}, signed blackout.start {roundId,stake}, then blackout.pick {roundId,cell} or blackout.cashout {roundId} |
Reservations return {roundId,expiresAt,commit} and last two minutes without locking money. First-chain preparation may return fairness_pending with retryAfterMs:3000; retry only that unsigned reservation. Signed bets and frozen terminal actions must be reconciled before any retry. Legacy Dice duels and 19-tile Blackout commands are offline-only.
Stake consent uses EIP-712 domain name Tilt, version 1, chain ID 99901, verifying contract the current vault, type Stake(player,roundId,amount,nonce,deadline). Its bytes32 round ID is the Keccak-256 of the returned UTF-8 server round ID. The consent binds the exact wallet, round, amount and unused nonce; it does not approve USDC.
Open-round and approval limits
These refusals come back as ordinary {ok:false,code,error} replies. They move no money.
| Code | When | What to do |
|---|---|---|
reservation_limit | The wallet already has 2 open rounds across all games. A background quote is refused once it has 1. Text: "Finish or cancel your open round first" | Finish or cancel a round, or wait for an unused reservation to lapse (two minutes), then retry |
reservation_pending | One network address opened too many rounds on the HTTP command route. The default is 30 a minute with a burst of 10. data.retryAfterMs says how long to wait | Wait that long, then retry |
session_grant_limit | A new play-session approval asked for more than 500 USDC or more than 7 days. Text: "Choose a spending limit of 500 USDC or less and a session of 7 days or less." | Sign a new approval within the limits |
A new play-session approval has a spending limit (the signed cap) of at most 500 USDC and a length (expiry) of at most 7 days, plus one hour of clock slack. The site's presets are 5, 20, 50 and 100 USDC and 1 hour, 24 hours, 3 days and 7 days. GET /api/account/play-session/status returns serverTime (Unix seconds) and defaults:{cap,expirySeconds,maxCap,maxExpirySeconds} as decimal strings: 20 USDC, 86,400 seconds, 500 USDC and 604,800 seconds. Approvals already active are not re-checked and work until they expire.
When Blackout cannot confirm the table's rules, a new round is refused with "Blackout is paused right now; your balance is safe."
Events
Table, tick, event and acknowledgement messages report accepted state. A visible animation or accepted cash-out is distinct from confirmed spendable payout. Saved outcomes retry while the UI reports settlement pending; FIFO queued profit is separately recorded onchain debt.
WebSocket messages
The house-game stream is mounted on /ws, multiplexed alongside the server's existing session transport. Joining sends a table view; command acknowledgements repeat the monotonic sequence. Signed stake consent is a sidecar to the command. Operator commands are never forwarded as player actions.
Hold'em API
Hold'em hands use plain HTTPS routes, not a socket.
Hold'em is coming soon, so the health route reports why hands are closed.
Routes
| Method/path | Auth | Purpose |
|---|---|---|
GET /api/holdem/health | None | {ok,ready,reason?,handKeyVersion,chainId,vault}; ready:false carries a reason such as practice_only |
POST /api/holdem/prepare | Bearer | {roundLabel,anteCents,clientSeed}; commits the hand's seed and returns the commit, chain, salt and the latest time the reserve can be signed |
POST /api/holdem/ante | Bearer | {roundLabel,nonce,deadline,signature,handKey?}; the signed reserve. Returns the hand view with your two cards and the flop |
POST /api/holdem/act | Bearer | {roundLabel,command:{requestId,street,decision},deadline,signature,handKey?}; one bet or fold on the next street |
POST /api/holdem/resume | Bearer | {roundLabel,handKey?}; returns the current view of a hand, for a reload or reconnect |
roundLabel is a version 4 UUID your browser makes for the hand. anteCents is a whole number from 10 to 500. clientSeed is 1 to 64 letters, digits, underscores or hyphens. street is flop, turn or river, and decision is bet or fold. A wallet gets one prepare every five seconds.
Flow
Call prepare, sign the reserve, send it to ante, then send up to three act calls in street order. The route needs four times the ante free in the vault and answers insufficient_balance if it is not. A repeated requestId with the same content changes nothing. A different content, a duplicate street or an out-of-order street is rejected. If the server cannot confirm a request it answers unavailable; call resume before you retry.
Signatures
The reserve is the same Stake consent the house games use, for four times the ante. Its nonce can bind a one-hand browser key, the handKey, so that key can sign Bet or Fold for that hand only. Without it your wallet signs each street. A street signature is typed data in its own Hold'em domain, bound to the chain and the vault. It covers your address, the round, the ante, the street, the decision, the amount bet, the request ID and a deadline.
Hand view and proof
Every response is a hand view: a version string, the street awaiting your decision, the ante, the reserved and committed cents, your cards, the board so far, the ordered decisions, the result and deadlineSeconds. That deadline is 90 seconds after the street opens. When it passes, the server records a fold. The dealer's cards appear only after the river bet. The deck stays on the server until the hand settles.
After settlement the view carries the settlement transaction and a fairness proof: commit, chain, seed index, salt, client seed, revealed seed, ante, the ordered decisions, outcome and gross return in cents. Recompute it with the fairness specification. Exact shapes are in the server's holdem-http.ts. Response time depends on public RPC pacing, wallet signing and confirmations. No concurrent-player capacity or instant settlement is claimed.