Skip to main content
Bankroll hosts your web app inside its mobile app — built for real-money games. The three things a real-money game needs before a user can play — verified identity, location, and payments — Bankroll already handles. Your app gets them from the host:
  • Identity — a signed token: who the user is (their Bankroll handle), that they’ve passed identity verification, and their age.
  • Geo — the user’s region as an ISO 3166-2 code, so you can enforce where play is allowed. Delivered in the same token as identity.
  • Payments — charge the user’s Bankroll balance to your wallet in one call.
You build the game; Bankroll brings the rails and the players. A Built-for-Bankroll app is an ordinary web app served from your own origin, and the @joinbankroll/sdk npm package is the whole integration — there is no wallet for your page to manage and no private keys anywhere near your code.

​
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: 
import { bankroll } from "@joinbankroll/sdk";

bankroll.status();   // 'unavailable' | 'update_required' | 'ready' — sync, SSR-safe
bankroll.identity(); // Promise<string> — a Bankroll-signed identity token scoped to your origin
bankroll.pay({ amountCents: 500 }); // Promise<string> — the settled payment's signature
Your page declares intent by calling it; the native Bankroll app is the trust boundary — it identifies the origin, asks the user for consent the first time, fetches signed identity tokens from Bankroll’s servers, and signs every payment. Your page never sees a wallet or 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 https://<your-origin>/.well-known/bankroll.json to learn your app’s name, icon, the capabilities it uses, and the wallet that receives payments. See The manifest.
3

The user consents once

The first time your app calls a capability, Bankroll shows the user exactly what your app will get (handle, region, age) and what it can do (charge their balance). They approve once, per app.
4

You call identity() and pay()

Get a verifiable identity 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, identity(), pay() }, injected before your page loads. You can call it directly, but the SDK is the supported surface: it feature-detects old hosts, caches identity tokens, validates pay input, and normalises every rejection into a typed BankrollError.

​
The trust model

The security of the integration comes from native being the only thing that signs, not from trusting your page:
  • Your page can ask for identity, but the token is minted and signed by Bankroll’s servers — your page cannot forge who the user is.
  • Your page can ask to charge an amount, but the recipient is always the merchantWallet in your manifest. A compromised page can over-charge a consented amount to your own wallet — it can never redirect funds elsewhere.
  • Everything the user shares is gated by an explicit, per-app consent prompt.
Opening a third-party app in Bankroll is in early access and currently limited. To get your app enabled, reach out to the Bankroll team — see Launch your app.

​
Next

Quickstart

Ship a working integration end-to-end — SDK, manifest, identity, pay, deep link.

The manifest

The /.well-known/bankroll.json your app serves.

Identity

Get and verify a signed identity token.

Payments

Charge the user’s balance and verify the payment.