02 — the money

The bank

The bank is the single source of truth for balances. You lock a stake, you settle a payout — the bank does the arithmetic atomically, feeds the shared jackpot, and pushes the fresh balance to the player's UI. You never hold or compute a balance yourself.

Basics


Base URL	`https://bank.domin8.fun`
Auth	header `X-API-Key: <BANK_API_KEY>` — server-side only, from env. Wrong key → `401`.
Amounts	decimal strings: `"5"`, `"12.50"` — never floats, never atomic units. Up to 9 decimals.

POST/bet/open

Locks the stake out of the player's available balance. Idempotent on bet_id — generate a unique id per spin and reuse it on retries.

request

{
  "bet_id":  "spin_u123_000042",   // YOUR unique id for this spin
  "user_id": "tg:123456789",       // from the verified JWT
  "token":   "sol",
  "amount":  "5",                  // the stake
  "game_id": "yourslot"
}

response 200

{ "bet_id": "spin_u123_000042", "status": "pending",
  "available": "95", "locked": "5" }

Status	Meaning
`402`	insufficient balance — tell the player, do not spin
`409`	this `bet_id` was already settled — treat as "already handled"

POST/bet/settle

Releases the lock and pays the win. Idempotent on bet_id. payout is the total returned to the player, not the profit — "0" settles a loss.

request

{ "bet_id": "spin_u123_000042", "payout": "12.50" }

response 200

{ "bet_id": "spin_u123_000042", "status": "settled",
  "payout": "12.50", "available": "107.50", "locked": "0" }

404 means no open bet under that bet_id. After a settle, the bank feeds the shared jackpot from the house gain and pushes the balance to the hub UI over websocket — nothing for you to do.

GET/balance/:user_id?token=sol

response 200

{ "available": "107.50", "locked": "0" }

Crash between open and settle?

The stake stays locked, the bet stays pending. Retry the whole spin with the same bet_id: the open returns the existing lock, the RNG re-deals the identical result (deterministic per seed + nonce), and you settle the same payout. No double-charge, no double-pay.

Settle every round — including losses

A losing spin must still be settled with payout: "0". Never leave a bet pending: the stake stays locked for the player and the jackpot pool under-feeds.

← Player session 03 — The RNG→