React helpers

@joinbankroll/sdk/react is the client-side glue that behaves identically in every app: reading host status without flashing the wrong screen through hydration, a fetch that carries the session token, and a development overlay. Your app’s own product surface stays in your app. react is an optional peer (>= 18), installed only if you use this entry.

Host status

import { useBankrollStatus, useBankrollChecked } from "@joinbankroll/sdk/react";

function Gate({ children }: { children: React.ReactNode }) {
  const checked = useBankrollChecked();
  const status = useBankrollStatus();

  if (!checked) return <Loading />;
  if (status === "unavailable") return <GetTheApp />;
  if (status === "update_required") return <UpdateTheApp />;
  return children;
}

useBankrollStatus() is bankroll.status() as a hook. The host is injected before your page loads and never changes afterwards, so there is nothing to subscribe to — the work these do is agreeing across the hydration boundary. useBankrollChecked() is why the pair exists. It is false during the server render and the first client paint, and true after. Render a loading state on it rather than deciding, or a phone already inside Bankroll sees “get the Bankroll app” until hydration corrects it. Server and client deliberately agree on 'unavailable' for the same reason: the wrong screen briefly is worse than no screen briefly.

Fetch with the session token

import { bankrollFetch } from "@joinbankroll/sdk/react";

await bankrollFetch("/api/orders", { method: "POST", body });

withBankrollToken(fetch), already built and bound. Binding matters — fetch throws when called detached from the window — and on the server it resolves to the bare global, so importing this module never crashes a render that doesn’t use it. In a plain browser the request goes out bare and your server answers 401.

Sending a user through verification

import { verifyIdentity } from "@joinbankroll/sdk/react";

if (!(await verifyIdentity())) return; // declined — leave them where they are

session({ identity: true }) reduced to the question a UI actually asks: true once the user is verified, false if they declined or the host refused. Anything that is not a host rejection propagates. Use it for an explicit “verify to continue” button; for gating a paid action, check session.user.identity on your server, which is the only place the answer is trustworthy.

Development overlay

import { DevTools } from "@joinbankroll/sdk/react";

{process.env.NODE_ENV === "development" && (
  <DevTools
    rows={[
      { label: "Origin", value: origin, ok: true },
      { label: "Treasury", value: treasury, ok: Boolean(treasury), copy: true },
      { label: "RPC", value: rpcUrl, ok: !usingPublicRpc },
    ]}
  />
)}

A floating panel reporting how the app is configured — the manifest’s origin, the treasury address, the RPC endpoint, whatever you pass. Rows marked ok: false render in amber, and copy: true truncates the display while putting the full value on the clipboard, since a shortened address you can’t copy is useless.

Render it only when you mean to. It carries addresses and endpoints, so gate it on your own development check — the component does not gate itself.

Field	Type	Description
`label`	`string`	Row label, and the key.
`value`	`string`	The full value — what gets copied.
`ok`	`boolean`	`false` renders the value as a warning.
`display`	`string`	Shown instead of `value` when the real thing is too long to read.
`copy`	`boolean`	Offer a copy button; `value` is what lands on the clipboard.

In a Next.js app the overlay also hides Next’s own dev badge, which otherwise stacks with it in a phone-sized viewport, and offers it back behind a toggle.

Get Started

Guides

Reference

Helpers

Changelog

Host status

Fetch with the session token

Sending a user through verification

Development overlay

​Host status

​Fetch with the session token

​Sending a user through verification

​Development overlay

Host status

Fetch with the session token

Sending a user through verification

Development overlay