Notifications

Your server can ask Bankroll to send a notification with your app’s name on the title. Tapping it opens a path on your app’s origin. Notifications require a Bankroll-signed manifest with a truthy capabilities.push and an attested signing key. See configuration and compatibility.

Methods

import { notifyUser, notifyAudience } from "@joinbankroll/sdk/server";

await notifyUser({
  origin: "https://acme.example",
  to: session.user.wallet, // from your verified session
  title: "Match ready",
  body: "Your opponent is ready to play.",
  path: "/app/matches/9",
});

await notifyAudience({
  origin: "https://acme.example",
  title: "New season",
  body: "Season two is open.",
  path: "/app",
});

Both return Promise<void>, resolving when Bankroll accepts the request for delivery. This is not confirmation that a device displayed it. notifyUser targets one Bankroll user; notifyAudience targets your configured recent-user audience. Bankroll applies your app’s audience and mute policies.

Field	Required	Meaning
`origin`	Yes	Your canonical HTTPS origin, matching the signed manifest.
`to`	`notifyUser` only	The recipient’s Bankroll wallet address.
`title`	Yes	Text after your app’s name. Trimmed; must be nonempty. Keep it short for device displays.
`body`	Yes	Notification text. Trimmed; must be nonempty.
`path`	No	Path on your own origin, starting with `/` but not `//`. Defaults to `/`.

Authentication

With BANKROLL_APP_KEY, the SDK sends a shared app JWT in the Authorization header and an application/json body:

Endpoint	JSON body
`POST https://api.joinbankroll.com/api/push`	`{ "to": "<wallet>", "title": "…", "body": "…", "path": "/app" }`
`POST https://api.joinbankroll.com/api/push/broadcast`	`{ "title": "…", "body": "…", "path": "/app" }`

path is optional. The authenticated token supplies the origin. BANKROLL_API_URL overrides the default API origin. With only BANKROLL_PUSH_KEY, the SDK preserves the legacy application/jwt request body, without an Authorization header. These JWTs use alg: EdDSA, iss: <app-origin>, aud: bankroll-push, and a 60-second SDK lifetime. The type is bankroll-push+jwt for unicast or bankroll-push-broadcast+jwt for broadcast; content is in title, body, and optional path, with the unicast recipient in sub. A legacy token does not grant general app access.

Errors

A refused request throws PushError; its code is Bankroll’s reason:

Code	Meaning
`unauthenticated`, `unauthorized`	Invalid shared or legacy authentication.
`app_not_verified`, `push_not_declared`	The signed manifest does not authorize this request.
`push_muted`	Bankroll has muted the app’s notification access.
`unknown_user`, `not_your_user`	Unknown recipient or recipient outside your app’s allowed audience.
`broadcast_not_configured`	Your app’s broadcast audience is not configured.
`invalid_request`, `invalid_title`, `invalid_body`, `invalid_path`	Invalid request fields.
`unavailable`, `push_not_enabled`	Bankroll cannot serve the request now.

Configuration and network failures can throw other errors. The SDK does not retry sends automatically; a lost reply may hide an accepted notification, so retrying can send it twice.

Get Started

Guides

Reference

Bankroll Verified

Helpers

Changelog

Methods

Authentication

Errors

​Methods

​Authentication

​Errors

Methods

Authentication

Errors