Give your site a bWalletX theme

When you build a service, ship its bWalletX theme. After a person approves a connection from your site, bWalletX fetches a small JSON file from your site and dresses your approval sheets in your colours with your logo. It’s free advertising on every sheet your users see.

✓ Live in the wallet (all editions with the current release). Few sites publish a file yet; badvertisingx.com is one.

What stays the wallet’s

The wallet’s own strip above your banner shows your true host and is never themed. Amounts, recipients, warnings and the Approve / Deny buttons keep the wallet’s fixed styling. A theme changes how your banner looks, nothing else.

Where to put it

https://<your-host>/.well-known/bwalletx-theme.json (checked first), or
a theme object inside https://<your-host>/.well-known/bapp.json (its top-level name is used if the theme has none).

Schema (`v: 2`)

Key	Required	Rule
`v`	no	If present, must be `2`
`$schema`	no	Ignored
`name`	yes	Plain text, 1-32 characters; letters, numbers, spaces and `. , ' & ! · : + -` only; no links or addresses
`mode`	yes	`"dark"` or `"light"`
`accent`	yes	`#RRGGBB`
`accentHi`	no	`#RRGGBB` (defaults to `accent`)
`bg`	yes	`#RRGGBB`
`surface`	yes	`#RRGGBB`
`text`	yes	`#RRGGBB`
`logo`	no	Same-origin URL (relative is fine), max 512 characters; PNG, JPEG, WebP, GIF or SVG, max 64 KB
`cardArt`	no	Same-origin URL; same image types, max 256 KB

Any other key and the whole file is refused.

Checks

File max 8 KB, fetched within 4 seconds, no cookies, no referrer.
A redirect to another origin is refused. Images must be on the same origin.
https only (plain http only for localhost and 127.x.x.x during development).
Text must read: text needs 4.5:1 contrast on both bg and surface. If it fails, the wallet swaps in black or white; if neither reads, the theme is refused.
Accent must show: accent needs 3:1 contrast on bg, or the theme is refused.
Text on the accent is chosen by the wallet (black or white).
Sites connected through a pairing relay never get a theme.

When it’s fetched

Only after the person approves a request from your site. Never before.
A theme is cached for 24 hours; “no theme” is cached for 1 hour. The wallet keeps the 50 most recent sites.
People can switch site themes off for everyone (Settings › Theme) or for one site (Connections › “Use this site’s theme”). Revoking a site forgets its theme.

A missing or broken file is never an error to the user: the sheet just looks normal.

Example

{
  "v": 2,
  "name": "Acme Coffee",
  "mode": "dark",
  "accent": "#F5B800",
  "accentHi": "#FFD24D",
  "bg": "#0B0A09",
  "surface": "#121110",
  "text": "#F3ECDC",
  "logo": "/logo.svg"
}

Serve it as application/json. Test: connect your site to bWalletX, approve one request, then trigger another: the sheet should show your banner.

Older family files (`v: 1`)

Sites in the b family may publish a v: 1 file (label, scheme, accent, hi, bg, surface, text…). The wallet reads it as a connect theme too (colours only, no images), and may offer it as a whole-wallet theme (“Wear … colours?”). New sites should use v: 2.

Status

✓ Live: connect themes on approval sheets
✓ Live: per-site and global off switches
◻ Coming: most b family sites publishing their file