API Reference

All game APIs are serverless functions under /api/* on the app origin. Auth for money-touching calls is the stateless wallet signature described in Crash Money Model. Responses are JSON; game state endpoints send cache-control: no-store.

Crash — `/api/crash`

`GET /api/crash?wallet=0x…&authSig=0x…`

Full state snapshot. Sweeps round commits, settlements and vault deposits before responding (self-healing — any instance can serve any state).

{
  "roundId": 481902,
  "phase": "betting",            // betting | flight | results
  "msLeft": 12345,
  "multiplier": 1.00,
  "crashPoint": null,            // secret until settle
  "edgeBps": 400,
  "history": [{ "roundId": 481901, "crash": 1.87 }],
  "recentWins": [{ "wallet": "0x…", "token": "ETH", "amount": "…", "mult": 2.5, "payout": "…" }],
  "me": { "chips": { "ETH": "…", "USDG": "…" }, "openBet": null, "nonce": 3 },
  "config": { "bounds": { "ETH": { "min": "…", "max": "…" } }, "depositFeeBps": 100 }
}

`GET /api/crash?action=verify-seeds`

Publishes (seed_hash, seed, pepper) for the last 12 settled bet-bearing rounds — the raw fairness disclosure (see Provably Fair).

`POST /api/crash` actions

Action	Body (beyond wallet+authSig)	Notes
`bet`	`token, amountWei`	Debits chips; one open bet per wallet per round; refunds ledger on any failure
`cashout`	—	Credits `amount × currentMultiplier`; only while in flight
`withdraw`	`token, amountWei, nonce, signature`	Relayer submits `CrashVault.withdraw`; player-signed, gasless
`house-topup`	—	Vault-owner-only: surfaces `houseNeedsFunding` when the relayer’s gas reserve is low

Entropy dice — `/api/entropy`

`GET /api/entropy`

Public config:

{
  "ok": true,
  "games": ["mines", "limbo", "plinko", "keno"],
  "bounds": { "ETH": { "min": "50000000000000", "max": "…" },
               "USDG": { "min": "10000", "max": "500000000" } },
  "plinkoTables": { "low": [...], "medium": [...], "high": [...] }
}

`POST /api/entropy`

{ "action": "play", "game": "mines", "token": "ETH", "amountWei": "10000000000000",
  "params": { "mines": 3, "pick": 7 }, "wallet": "0x…", "authSig": "0x…" }

Response carries the settled result with fairness data (seedHash, seed, meta with mine positions / draws / bucket), plus the payout. action: "recent" returns the recent-results feed for the in-app strip. Games: mines (params: mines, pick), limbo (target), plinko (risk, bucket derived server-side), keno (picks[]).

Lootbox — `/api/lootbox`

Endpoint	Purpose
`GET /api/lootbox`	Public config: price, pool, prize table, recent wins
`POST` (pay → verify flow)	Client sends the payment tx hash; server verifies `to == pool, value == price` on-chain, rolls the tier, pays the prize (stock tiers swap + send xStock directly)
`POST` share-to-spin	One free DUST open per UTC day; verifies the shared post via oEmbed

LootBox NFT — `/api/lootbox-nft`

Call	Body	Effect
`GET ?wallet=…`	—	Your boxes (closed/revealed), tiers, prices, stats
`POST action:buy`	`kind`	Server-side buy coordination → client submits payable `LootBoxNFT.buy()` (wallet prompt 1)
`POST` (reveal)	`boxId`	Server rolls tier from `keccak(boxId ‖ pepper)` and signs the open commitment (free, no wallet prompt beyond submitting)
`POST action:claim`	`boxId`	Verifies the on-chain reveal, credits the DUST prize via `StardustWheel.claimAward` with the same nonce (wallet prompt 3)

Flow guarantee: three wallet prompts total, never more — buy (payable), open (submits the signed commitment), claim (free DUST cash).

Wallet bridge — `/api/wallet/*` (vfair platform)

Implements the partner-wallet contract the vfair-games platform calls during real-money play, backed by the same crash-chip ledger:

GET  /api/wallet/balance?playerId=&currency=   → { balance }
POST /api/wallet/transaction                   → { partnerTransactionId, balance, balanceBefore }

Auth: partner JWT (HS256, ≤30s TTL) in the Authorization header, verified with node:crypto in constant time.
playerId = the player’s wallet address; currency = chip token (ETH/USDG); amounts in whole units (1.0 = 1 token).
Idempotency keys are persisted (vfair_wallet_txs) so platform retries can never double-move funds.

RPC proxy — `/api/rpc`

Same-origin JSON-RPC proxy for the Robinhood chain RPCs. The public RPC sends a malformed CORS header (Access-Control-Allow-Origin: *,*), which browsers hard-reject; the proxy performs upstream calls server-side and answers from our own origin with a single valid CORS header. Upstreams are allowlisted.

Rate limits & reliability notes

Game state endpoints are read-heavy and cheap; they always self-sweep pending work before answering.
Money endpoints verify auth signatures against the current and previous 24h window — a once-a-day signature is sufficient.
All ledger mutations are idempotent per round/nonce; replays from clients or the platform are safe by construction.

Overview

Payment Structures

Casino Economy

Earn & Lending

Monetization

Reference

Api

API Reference

Crash — `/api/crash`

`GET /api/crash?wallet=0x…&authSig=0x…`

`GET /api/crash?action=verify-seeds`

`POST /api/crash` actions

Entropy dice — `/api/entropy`

`GET /api/entropy`

`POST /api/entropy`

Lootbox — `/api/lootbox`

LootBox NFT — `/api/lootbox-nft`

Wallet bridge — `/api/wallet/*` (vfair platform)

RPC proxy — `/api/rpc`

Rate limits & reliability notes

​API Reference

​Crash — /api/crash

​GET /api/crash?wallet=0x…&authSig=0x…

​GET /api/crash?action=verify-seeds

​POST /api/crash actions

​Entropy dice — /api/entropy

​GET /api/entropy

​POST /api/entropy

​Lootbox — /api/lootbox

​LootBox NFT — /api/lootbox-nft

​Wallet bridge — /api/wallet/* (vfair platform)

​RPC proxy — /api/rpc

​Rate limits & reliability notes

API Reference

Crash — `/api/crash`

`GET /api/crash?wallet=0x…&authSig=0x…`

`GET /api/crash?action=verify-seeds`

`POST /api/crash` actions

Entropy dice — `/api/entropy`

`GET /api/entropy`

`POST /api/entropy`

Lootbox — `/api/lootbox`

LootBox NFT — `/api/lootbox-nft`

Wallet bridge — `/api/wallet/*` (vfair platform)

RPC proxy — `/api/rpc`

Rate limits & reliability notes