The manifest

Every app declares itself with a manifest served at /.well-known/bankroll.jwt on its own origin. Bankroll fetches it over HTTPS to learn three things: what your app is called, which capabilities it uses, and the address that receives its payments. Because Bankroll reads it from your origin, the baseline manifest is bound to your app by where it’s served. It is an Unsecured JWT with alg: none and an empty signature; you need no manifest-signing key. Verified apps serve a Bankroll-signed version and can declare an app key for server API calls.

Claims

Decoded, the manifest payload is a small JSON object:

{
  "manifestVersion": 1,
  "sub": "https://acme.example",
  "aud": "bankroll-app-host",
  "capabilities": {
    "session": true,
    "payments": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
  },
  "name": "Acme Games",
  "launch": "/app",
  "supportUrl": "https://help.acme.example"
}

Claim	Required	Description
`manifestVersion`	Yes	The manifest format version. Currently the integer `1`.
`sub`	Yes	Your app’s exact canonical origin (`scheme://host[:port]`, default port omitted; no path, no trailing slash). Must equal the origin Bankroll loaded — this is what binds the manifest to your app.
`aud`	Yes	Always the string `bankroll-app-host`.
`capabilities`	Yes	Declares what your app uses. `session: true` lets it open a user session (`session()`); `payments: "<address>"` enables payments and fixes the address every `charge()` settles to. A verified app can declare `push: true` to enable notifications. At least one capability must be enabled.
`appKey`	No	Your server authentication public key: a base58 Ed25519 public key (32 bytes), separate from the payments address. Required for shared app authentication. See key configuration.
`name`	No	Your app’s display name, shown to the user. Defaults to your origin if omitted.
`launch`	No	Where Bankroll opens your app from its tile: a path starting with `/` (not `//`), resolved against your origin. Omit to open your origin’s root. Use it to keep a marketing page at `/` and the app itself at, say, `/app`. Deep links a user follows are opened as given.
`supportUrl`	No	Where your users get help. Bankroll shows it in your app’s menu as “Help with <your app>”, and opening it hands the URL to the operating system — so a help page, a `mailto:`, a `tel:`, or a chat invite all work, and whichever app claims that link opens it. It may point anywhere; support desks usually live on another domain. Omit it and no menu item appears.
`appTokens`	No	Tokens your app issues itself, keyed by mint: `{ "<mint>": { "name": "…", "description": "…" } }`. Declaring one lets `charge()` settle in it and shows it in the user’s wallet as your app’s funds. It is also a limit — your app can charge HSUSD or these mints, and nothing else. See App tokens.

App key and notifications

appKey names the public key your server uses for app authentication. The private key stays on your server. manifestRoute includes the public key by default when the app credential is configured. To enable notifications, set push: () => true on manifestRoute; this declares capabilities.push: true. A false or null result omits the capability. Having an appKey alone does not enable notifications, and declaring either field does not replace Bankroll verification. Legacy public-key strings in capabilities.push remain supported. A valid appKey takes precedence over that string. See legacy keys for configuration and upgrade behavior.

Your icon

Your icon is not a manifest claim. Serve a square PNG (256×256 or larger) at the fixed path /.well-known/bankroll-icon.png on your origin — a sibling of the manifest. Bankroll fetches it from there and shows it on your app’s tile and in Connected Sites; until you serve one, it shows a monogram of your app’s name. A manifest that still includes an iconUrl claim remains valid — the claim is simply ignored.

Updating your icon — `iconDigest`

If you replace the PNG at the same path, users who have already connected your app can keep seeing the old one. To make an update reach them, add the OPTIONAL iconDigest claim: a hash of the icon bytes as a Subresource Integrity hash-expression (sha256-<base64>). Bankroll treats a changed iconDigest as a manifest change, so your new icon propagates to connected users. Compute it from the exact bytes you serve, and omit the claim if you don’t serve an icon:

import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";

const pngBytes = readFileSync("public/.well-known/bankroll-icon.png");
const iconDigest = "sha256-" + createHash("sha256").update(pngBytes).digest("base64");
// → "sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="

On Next.js, pass it to manifestRoute’s optional iconDigest and the SDK handles the omission rules.

The recipient is read from the fetched manifest, never supplied by your page. For a session-only app, omit payments and set session: true alone.

Rules

Served on your origin. The manifest must live at the exact path /.well-known/bankroll.jwt on the same origin your app loads from. Bankroll matches by origin (scheme + host + port), so https://acme.example and https://app.acme.example are different apps with different manifests — and each manifest’s sub must equal its own origin.
application/jwt. Serve it with Content-Type: application/jwt, no larger than 8 KiB, over HTTPS. Your app URL must be HTTPS too.
Unsigned baseline. Its header is exactly { "alg": "none", "typ": "bankroll-app-manifest+jwt" }, and the signature segment is empty — the token is header.payload., with a trailing dot and nothing after it. Verified apps instead serve the Bankroll-signed JWT verbatim.
Must be valid. If the manifest is missing, unreachable, malformed, the wrong media type, or its sub / aud / manifestVersion are wrong, session() and charge() reject with manifest_error.
Declare what you use. Any capability you call must be enabled here. Calling one you didn’t declare rejects with capability_not_registered. See error codes.
Changing it re-asks your users. A user’s grant is bound to the exact manifest they approved, so editing any claim — including name and supportUrl — means everyone who already connected your app is asked to approve it again on their next visit. Treat these as settings you pick once. Where a value may need to move later, point it somewhere you control and redirect: https://acme.example/support can change destination freely, but editing the claim itself cannot.

Serving it

On Next.js, manifestRoute() from @joinbankroll/sdk/next is the whole route. You declare what is genuinely your app’s — its name, where it launches, where payments settle — and the SDK owns the format, so a change to the format arrives with an npm upgrade rather than a diff you have to write:

// app/.well-known/bankroll.jwt/route.ts
import { manifestRoute, treasuryAddress } from "@joinbankroll/sdk/next";

// Built from the request's own host, so it cannot be prerendered.
export const dynamic = "force-dynamic";

export const GET = manifestRoute({
  name: () => "Acme Games",
  launch: "/app",
  payments: () => treasuryAddress(),
  supportUrl: () => "https://acme.example/support",
  appTokens: () => ({
    "7Nk3…": { name: "Acme Chips", description: "Play credit for Acme Games" },
  }),
});

sub is taken from the request’s own host, so preview deployments, custom domains, and local tunnels each declare themselves correctly with nothing to configure. payments returning null omits the capability rather than advertising an address the app cannot honor — which is what treasuryAddress() does before a treasury key is set. supportUrl and appTokens are omitted from the payload entirely when they resolve to nothing, because an empty claim is still a claim and would re-ask every connected user for consent once it gained a value.

Any other stack

The unsigned baseline is two Base64URL-encoded JSON segments joined by dots, with an empty signature. Building it by hand takes a few lines:

const b64url = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");

app.get("/.well-known/bankroll.jwt", (req, res) => {
  const origin = `https://${req.headers.host}`;
  const header = { alg: "none", typ: "bankroll-app-manifest+jwt" };
  const payload = {
    manifestVersion: 1,
    sub: origin,
    aud: "bankroll-app-host",
    capabilities: { session: true, payments: process.env.PAYMENT_ADDRESS },
    name: "Acme Games",
  };
  res.type("application/jwt").send(`${b64url(header)}.${b64url(payload)}.`);
});

require "base64"
require "json"

# config/routes.rb: get "/.well-known/bankroll.jwt" => "manifests#show"
class ManifestsController < ApplicationController
  def show
    b64url = ->(o) { Base64.urlsafe_encode64(JSON.generate(o), padding: false) }
    header = { alg: "none", typ: "bankroll-app-manifest+jwt" }
    payload = {
      manifestVersion: 1,
      sub: "https://#{request.host}",
      aud: "bankroll-app-host",
      capabilities: { session: true, payments: ENV["PAYMENT_ADDRESS"] },
      name: "Acme Games"
    }
    render plain: "#{b64url[header]}.#{b64url[payload]}.",
           content_type: "application/jwt"
  end
end

import base64, json
from fastapi import Request, Response

def b64url(o: dict) -> str:
    return base64.urlsafe_b64encode(json.dumps(o).encode()).rstrip(b"=").decode()

@app.get("/.well-known/bankroll.jwt")
def manifest(request: Request):
    header = {"alg": "none", "typ": "bankroll-app-manifest+jwt"}
    payload = {
        "manifestVersion": 1,
        "sub": f"https://{request.headers['host']}",
        "aud": "bankroll-app-host",
        "capabilities": {"session": True, "payments": os.environ["PAYMENT_ADDRESS"]},
        "name": "Acme Games",
    }
    return Response(f"{b64url(header)}.{b64url(payload)}.",
                    media_type="application/jwt")

Before testing your app, make sure the manifest is live and well-formed — fetch it and decode the middle segment to check your claims:

curl https://acme.example/.well-known/bankroll.jwt
# → header.payload.

Get Started

Reference

Bankroll Verified

Helpers

Self-hosted

Changelog

Claims

App key and notifications

Your icon

Updating your icon — `iconDigest`

Rules

Serving it

Any other stack

​Claims

​App key and notifications

​Your icon

​Updating your icon — iconDigest

​Rules

​Serving it

​Any other stack

Claims

App key and notifications

Your icon

Updating your icon — `iconDigest`

Rules

Serving it

Any other stack