Skip to main content
Before a real-money app can let a user play, it needs the user’s age, the user’s location, and a way to move money. When Bankroll opens your app inside its mobile app, the host supplies all three:
  • Age — a Bankroll-signed session token carrying the user’s handle and their verified age. Verification is performed once, platform-wide, by Bankroll; your app reads the result from the token and applies its own eligibility rules. One person, one account.
  • Geo — the user’s region in the same token, as an ISO 3166-2 code (US-NY) or a bare country code when only the country resolves. Where you may operate remains your determination.
  • Payments — charge() charges the user’s Bankroll balance and settles directly to the address fixed in your manifest (capabilities.payments); you are not in the deposit path. Settlement is final (no chargebacks) and Bankroll charges no fee.
Your side is a web app served from your own origin; the client integration is the @joinbankroll/sdk npm package.

​
How it works

When Bankroll opens your site, it injects a small host object into your page before it loads. The SDK wraps that host with host detection, token caching, input validation, and typed errors:
Bankroll’s app handles the wallet, keys, and signing; your page never constructs a transaction.
1

A user opens your app

From a Bankroll deep link — https://joinbankroll.com/play?url=<your-app-url> — the Bankroll app loads your site in its host webview.
2

Bankroll reads your manifest

The host fetches <your-origin>/.well-known/bankroll.jwt — a small manifest (an unsigned JWT) declaring your app’s name, the capabilities it uses, and the address that receives payments. It’s bound to your app by where it’s served, not by a signature. Your icon is served beside it at /.well-known/bankroll-icon.png. See The manifest.
3

The user connects your app

The first time your app opens a session or takes a payment, the user connects it — once, per app. Each charge is still shown to the user to approve; a decline rejects your call with a typed error.
4

You call session() and charge()

Get the session token; charge the user’s balance. Verify both on your server before granting anything of value.
Under the hood, the host is window.bankroll — { version, session(), pay() }, plus haptics() and the prerelease balances() and deposit() on a current host, injected before your page loads (the SDK’s charge() maps to the host’s pay method — the wire name predates the rename). You can call it directly, but the SDK is the supported surface: it feature-detects each method, so a host too old to have one rejects with update_required instead of throwing a TypeError, and it normalises every rejection into a typed BankrollError.
Paying users — winnings, refunds — isn’t a host capability: your server transfers HSUSD to the user’s wallet address (session.user.wallet). See Paying a user.
Built-for-Bankroll is open: publish a valid manifest on your origin and your app runs — no registration or approval to be opened via a /play link. Being bundled into the Bankroll app itself (featured, first-party placement) is a separate step that requires Bankroll approval. Bankroll is not a gaming regulator and takes no responsibility for your licensing or compliance; operating lawfully in the regions you serve is your responsibility.

​
Next

Quickstart

SDK, manifest, session verification, a payment, and the deep link.

The manifest

Claims, rules, and serving /.well-known/bankroll.jwt.

The session token

Claims, server-side verification, and eligibility gating.

Payments

charge() input, idempotency, server-side verification, error codes.

Paying a user

Payouts and refunds as HSUSD transfers to the user’s wallet.

Next.js helpers

The origin, the session on a request, the manifest route, the treasury.

The store

Durable JSON with the two guarantees a payment record needs.