> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinbankroll.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Bankroll handles the verified identity, geolocation, and payments a real-money game needs — in a web app that runs inside the Bankroll app.

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`](https://github.com/inplayinnovation/bankroll-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:

```ts theme={null}
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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](/build/manifest).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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`](/build/payments#error-codes).
</Note>

## 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.

<Note>
  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](/build/quickstart#launch-your-app).
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/build/quickstart">
    Ship a working integration end-to-end — SDK, manifest, identity, pay, deep link.
  </Card>

  <Card title="The manifest" icon="file-lines" href="/build/manifest">
    The `/.well-known/bankroll.json` your app serves.
  </Card>

  <Card title="Identity" icon="fingerprint" href="/build/identity">
    Get and verify a signed identity token.
  </Card>

  <Card title="Payments" icon="wallet" href="/build/payments">
    Charge the user's balance and verify the payment.
  </Card>
</CardGroup>