Wallet modes

Hosted wallet — fastest

The operator platform holds a player ledger for your merchant account. Money commands settle inside the platform, in the same transaction as the order — there are no wallet hooks in the path at all, so there is no hook code to write and no callback to keep up. You top players up through the merchant console (or its API) and read balances through the same B2B reads as everyone else. You still sign your own B2B calls. Same four steps as everyone else, domain included, in the Quick Start.

Self-hosted wallet — full control

You hold funds in your own ledger. The operator debits and credits players by calling wallet hooks you implement. This is the seamless-wallet model: there is no explicit "freeze" primitive — a stake is deducted outright by /wallet/bet, and anything returned comes back through the path that names why: /wallet/payout for a settled win, /wallet/cashout for closing early, /wallet/refund for a voided order. Route them separately even if the ledger entry is identical — the distinction is what your reconciliation reads back. Every money hook is idempotent by idem_key.

Custody is declared, not inferred. Each merchant carries an explicit wallet-mode setting on the operator side, and that declaration — not the presence of a hook row — decides where every command routes. Saving a working hook configuration does not transfer custody: while the mode says hosted, money keeps settling on the operator ledger until the mode itself is migrated, hook or no hook. And in self-hosted mode nothing falls back the other way: a hook that is unusable — switched off, blank base URL, missing entirely, or the lookup itself failing — is refused, and all four money commands and the balance read answer upstream_error. Disabling your hook stops trading; it does not hand the wallet back. That is deliberate; the alternative is a silent change of custody in the middle of a player's session.

One timing detail for rotations: the hook configuration is cached in-process for 30 seconds, so a change to your base URL can take that long to take effect and the old and new URLs may both receive commands during the window. Keep the previous endpoint answering until it has passed.

• • Implement all five hooks — bet, payout, cashout, refund and balance. The four money commands share one body and one response shape, but they are four separate paths: a path you do not serve is a 404 on a real money command. See Wallet hooks.
• • Verify every hook's signature (a distinct canonical from B2B — see Authentication).
• • Sign your own B2B calls to place orders and read quotes — see B2B API.