Tilt Docs Play
Docs

Developers

Game server API

On this page
  1. Conventions
  2. Account host
  3. Accounts and sessions
  4. Wallet sign-in
  5. Account commands
  6. House-game API
  7. Tables and seeds
  8. History and verification
  9. Commands
  10. Open-round and approval limits
  11. Events
  12. WebSocket messages
  13. Tilt Hold'em API
  14. Routes
  15. Flow
  16. Signatures
  17. Hand view and proof

The game server handles wallet sessions, the house games and Tilt 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
Tilt 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. requestId is a short code; quote it to support, which can find the matching server log. Over WebSocket the acknowledgement carries the same text without a requestId.
  • 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/pathAuthPurpose
GET /api/account/healthNoneAccount host and receipt-sync status
POST /api/account/wallet/challengeNone{address} returns the exact sign-in message
POST /api/account/wallet/loginNone{address,signature,name?} returns token/account on success
POST /api/account/wallet/link/challengeBearerChallenge for linking a wallet to an existing account
POST /api/account/wallet/linkBearerVerify its personal-message signature
GET /api/account/meBearerAccount, mirrored balance and queued account events
GET /api/account/vault-balanceBearer, 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

  1. Request a challenge for your address.
  2. Sign that exact message with EIP-191 personal-sign.
  3. 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.

PurposeResponse/request
HealthEnable play only for readiness.testnetPlayReady:true (the field keeps its original name), status ready, correct chain/vault and active table
ReleaseThe 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 errorsvault.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
CommandBearer-authenticated {cmd,stakeAuthorization?}; returns {ok,code?,error?,data?}
Your historyBearer-authenticated {bets,next}, opaque cursor
VerifyReturned 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

GameSequence
Crash Towercrash.bet {tableId,stake,autoCashout} with stake consent; crash.cashout {roundId}
Dicedice.reserve {tableId,stake}, then dice.spot {tableId,roundId,stake,direction,targetCents} with consent
Blob Flipflip.reserve {tableId,stake}, then flip.bet {tableId,roundId,stake,call} with consent
Blackoutblackout.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.

CodeWhenWhat to do
reservation_limitThe 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_pendingOne 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 waitWait that long, then retry
session_grant_limitA 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.

Tilt Hold'em API

Tilt Hold'em hands use plain HTTPS routes, not a socket. Tilt Hold'em is coming soon, so the health route reports why hands are closed.

Routes

Method/pathAuthPurpose
GET /api/holdem/healthNone{ok,ready,reason?,handKeyVersion,chainId,vault}; ready:false carries a reason such as practice_only
POST /api/holdem/prepareBearer{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/anteBearer{roundLabel,nonce,deadline,signature,handKey?}; the signed reserve. Returns the hand view with your two cards and the flop
POST /api/holdem/actBearer{roundLabel,command:{requestId,street,decision},deadline,signature,handKey?}; one bet or fold on the next street
POST /api/holdem/resumeBearer{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.