App status & offers

Bankroll reads https://<your-origin>/.well-known/bankroll-status when it shows your tile. Answer with what you have on offer for the person asking and the tile gets a ring and your headline; answer nothing and it doesn’t. That is the whole effect: the document is decorative, per user, per moment, and grants nothing.

The request

GET /.well-known/bankroll-status, no ambient credentials, at most five same-origin redirects, 2 seconds, application/json, body ≤ 1 KiB. Anything else — slow, large, wrong type, unparseable — reads as “no offer”, never as an error.
If the user has already connected your app, the request carries Authorization: Bearer <token> naming the user, scoped to your origin — verify it with verifyToken(token, { audience: origin }) from @joinbankroll/sdk/server and answer for that wallet. It identifies; don’t treat it as a login. No token means a user who hasn’t connected you yet — respond with your generic new-user offer (a welcome bonus, a first-deposit match), the same answer for everyone.
Per-user answers must not be cached: send cache-control: no-store.

The response

{ "offers": [{ "headline": "Double your first deposit", "key": "cmszndqd20000l204ga84lvgq" }] }

offers is an ordered array; Bankroll shows the first entry and ignores the rest (keep it to a few — the whole body must stay under 1 KiB). The app asks once each time the Home screen mounts, draws a ring on your tile for the first offer, and clears it when the tile is tapped. An entry is an object with two optional members, or true for an offer with no details:

Member
`headline`	≤ 64 characters, drawn as a one-line banner on the tile; aim for ~30 so it fits. Over the limit it is dropped, not truncated.
`key`	≤ 64 characters, opaque to Bankroll. When the user opens your app from the ringed tile it comes back as `?offer=<key>` on your launch URL, so your app knows which offer they tapped. It doesn’t change where the app opens.

Absent, null, [], false, or anything unrecognized means no offer.

Example

// app/.well-known/bankroll-status/route.ts
import { verifyToken } from "@joinbankroll/sdk/server";

export const dynamic = "force-dynamic";

export async function GET(request: Request) {
  const auth = request.headers.get("authorization");
  const origin = `https://${request.headers.get("host")}`;
  const session = auth?.startsWith("Bearer ")
    ? await verifyToken(auth.slice(7), { audience: origin })
    : null;

  const offers = session
    ? await offersFor(session.user.wallet)   // this user's open offers, best first
    : await newUserOffer();                  // no token: the generic new-user offer

  return Response.json({ offers }, { headers: { "cache-control": "no-store" } });
}

Nothing here is load-bearing: a bad token, a slow query, or an empty answer costs the user a ring, not a session. Don’t put state your app depends on behind it, and don’t tell an anonymous caller anything you wouldn’t print on a poster.

Get Started

Guides

Reference

Helpers

Changelog

App status & offers

The request

The response

Example

​The request

​The response

​Example

The request

The response

Example