Next.js helpers

Every Built-for-Bankroll app needs the same few things on the server, and none of them are app-specific: knowing which origin it is served from, verifying the session token on a request, serving the manifest, and holding a treasury. @joinbankroll/sdk/next is those, so they are an upgrade rather than a file you maintain. The entry is server-only — it imports next/headers, which throws in a client bundle, so a mistake fails at build rather than shipping the wrong thing to a browser. Nothing here is required: every helper is a convenience over verifyToken and the manifest format, both of which any stack can use directly.

The origin

import { getOrigin } from "@joinbankroll/sdk/next";

const origin = await getOrigin(); // 'https://acme.example'

Your app’s origin, read from the request’s own host header — so preview deployments, custom domains, and local tunnels each identify themselves correctly with nothing configured. It is the audience a session token is minted for and the sub a manifest claims, which is why it is never guessed: an origin inferred from a deployment environment variable would verify tokens for somewhere the app is not actually served from.

getOrigin() throws outside a request, so every route that reaches it must opt out of prerendering:

export const dynamic = "force-dynamic";

The SDK cannot declare that for you — Next reads it only from the route file itself. That covers the manifest route and any route resolving a session.

The session on a request

import { requireSession, requireIdentity, Unauthorized } from "@joinbankroll/sdk/next";

export const dynamic = "force-dynamic";

export async function POST(request: Request) {
  const session = await requireSession(request); // throws Unauthorized
  requireIdentity(session);                      // throws unless verified

  // session.user.wallet — the user's stable id, and payout target
}

Helper	Behavior
`getSession(request)`	Reads `x-bankroll-token`, verifies it against Bankroll’s public keys with `audience: await getOrigin()`, and returns the `BankrollSession` — or `null` for a missing, forged, expired, or wrong-app token.
`requireSession(request)`	The same, throwing `Unauthorized` instead of returning `null`.
`requireIdentity(session)`	Throws unless `session.user.identity` is truthy. Real money moves only for a verified person — gate every paid action on it.

Because the audience comes from getOrigin(), a token minted for another app can never authenticate a user on yours, and there is no origin constant to keep in step across environments. Unauthorized is a plain Error subclass — map it to a 401 wherever you handle route errors:

try {
  const session = await requireSession(request);
} catch (error) {
  if (error instanceof Unauthorized) {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }
  throw error;
}

The manifest route

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

export const dynamic = "force-dynamic";

export const GET = manifestRoute({
  name: () => "Acme Games",
  launch: "/app",
  payments: () => treasuryAddress(),
});

manifestRoute(app) returns the GET handler for /.well-known/bankroll.jwt. You supply what is genuinely your app’s; it fills in sub, aud, manifestVersion, and the capability shape.

Field	Required	Type	Description
`name`	Yes	`() => string`	Your app’s display name, as Bankroll shows it when someone connects.
`launch`	Yes	`string`	Where the host boots your app — a path resolved against your origin. The origin usually serves a landing page, so without this the host opens the lander.
`payments`	Yes	`() => string \| null`	The address charges settle to. Returning `null` omits the capability entirely, so an app that hasn’t finished setup advertises only what it can honor.
`supportUrl`	No	`() => string \| null`	Where your users get help. Omitted from the payload when it resolves to nothing.
`iconDigest`	No	`() => string \| null`	A Subresource Integrity hash of your icon’s exact bytes (`sha256-<base64>`). A changed digest is a manifest change, which is what carries a replaced icon to connected users. Omitted when it resolves to nothing — omit it whenever you serve no icon.
`appTokens`	No	`() => Record<string, { name?, description? }>`	The tokens your app issues, keyed by mint. Omitted when empty — an absent claim means only HSUSD may settle your charges, which is not the same as an empty one.

Each is a function rather than a value because it is evaluated per request: payments can start returning an address the moment a treasury key is set, without a redeploy. Entries whose name or description is an empty string are dropped rather than served, since one invalid entry would take the whole manifest down with it. See The manifest for what each claim means to the host, and for building one on another stack.

The treasury

Your app’s one secret is BANKROLL_TREASURY_KEY, a base58 Solana secret key. These read it, and are re-exported from @joinbankroll/sdk/server too:

import { treasuryAddress, requireTreasury } from "@joinbankroll/sdk/next";

treasuryAddress();   // 'J6L3…' — the public address, or null when unset
requireTreasury();   // the PaymentSigner, or throws with the setup instruction
treasurySigner();    // the PaymentSigner, or null when unset

The address is derived from the secret key, so the payment address your manifest advertises can never drift from the wallet that actually signs — pass treasuryAddress straight to manifestRoute’s payments. An app runs fine with no treasury: it simply can’t take or send money, and says so in its manifest. That is why the accessors answer “not configured” rather than throwing, and only requireTreasury() — what a money path calls — fails.

pay() already defaults to this signer, so a payout needs nothing passed. Reach for requireTreasury() when you need the signer itself — a custom instruction, or minting an app token. See Paying a user.

Get Started

Guides

Reference

Helpers

Changelog

The origin

The session on a request

The manifest route

The treasury

​The origin

​The session on a request

​The manifest route

​The treasury

The origin

The session on a request

The manifest route

The treasury