bWallet / bWalletX

The BSV wallet for tokens, media and apps, by The Bitcoin Corporation Ltd. Non-custodial: keys are encrypted on your device and never leave it.

App	Where	What
bWallet	App Store, Google Play	Store build: send, receive, tokens, media, names; Market is view-only
bWalletX	Android APK, private iOS, Chrome extension, bwalletx.com	Everything: Market trading, token rooms, tickets, $handle tokens, the b agent

• Phone apps: Capacitor build of the wallet UI (src/mobile/). Channels and store rules: src/mobile/channel.ts, src/mobile/storeBuild.ts, scripts/channel-build.sh. See MOBILE.md.
• Chrome extension (bWalletX): the full app in Chrome's side panel; pnpm build, output in build/. Sites find it with the brc100:announceWallet event (src/brand/discovery.ts).
• Branding: upstream files stay unchanged; names, logos and screens are swapped in at build time (vite.brand.ts, vite.config.mobile.ts).

pnpm install
pnpm build            # bWalletX Chrome extension → build/
pnpm build:mobile     # phone web bundle → build-mobile/
bash scripts/channel-build.sh android-direct   # or ios-store | ios-private | android-play
bun test src

Based on Yours Wallet

bWallet is a fork of Yours Wallet (MIT, © 2024 Daniel Wagner, David Case), and is not affiliated with or endorsed by its authors. The Yours-branded mobile port we shared with the Yours team is tagged yours-mobile-v0.1. The rest of this README is upstream's, describing the Yours Wallet extension this code builds on.

What It Does

Yours Wallet manages BSV, 1Sat Ordinals, BSV-21 tokens, and MNEE stablecoins from a single Chrome extension. It uses the BRC-100 wallet standard for transaction management, which means your wallet tracks both your keys and your transaction history to locate assets on-chain.

Key Features

• Non-custodial — Private keys are encrypted and stored locally. They never leave your device.
• BRC-100 architecture — Modern transaction system with invoices, output tracking, and certificate management.
• Remote storage — Back up your transaction history to a remote server. Sync across multiple devices with the same keys. Choose from known providers or run your own.
• On-chain identity — Publish a BAP identity profile (name, avatar, bio) directly to the blockchain.
• Multi-account — Manage multiple accounts from a single wallet.
• 1Sat Ordinals — View, transfer, list, and cancel listings. Multi-select with mode locking (transfer or cancel, not both).
• BSV-21 tokens — View balances, send tokens with full decimal precision.
• MNEE stablecoin — Native MNEE USD support with send and receive.

Architecture

Chrome Extension (popup UI)
  ├── React + Framer Motion frontend
  ├── CWI → background service worker (BRC-100 wallet interface)
  └── @1sat/actions (send, inscribe, lock, identity, etc.)

Background Service Worker
  ├── @1sat/wallet-browser (wallet factory)
  ├── @bsv/wallet-toolbox-mobile (storage, sync, monitor)
  ├── WalletPermissionsManager (BRC-100 permission grants)
  └── Remote storage (active + backup via wallet-toolbox)

Storage Model

Your wallet data lives in one active storage location and can be backed up to additional backup remotes:

• Local (default) — Browser IndexedDB. Data lives only on this device.
• Remote active — A BRC-100 storage server. All devices with your keys sync here. Enables multi-device access.
• Remote backups — Copies of your data on additional servers for safety.

New wallets start local-only. Users add remotes from the provider list or enter a custom URL.

Payment for Storage

Storage uses metered pricing. Each provider offers free baseline capacity (typically 1 GB). Usage beyond that is billed in satoshis per GB. Payments happen transparently — the SDK catches HTTP 507 responses and auto-pays via BRC-29 derivation. Users consent once during onboarding; after that, it's invisible.

Becoming a Storage Provider

Anyone can run a BRC-100 storage server using the 1sat serve command. Offer free community storage, run a paid service, or just host your own personal backup.

bunx @1sat/cli init
1sat config set server.accounts.enabled true
1sat config set server.accounts.baselineBytes 1073741824  # 1 GB free
1sat serve

See the full guide: Remote Storage Provider Guide

To appear in the wallet's provider picker, submit a PR adding your server to src/components/ProviderPicker.tsx.

Development

Prerequisites

• Bun
• Chrome browser

Setup

git clone https://github.com/yours-org/yours-wallet.git
cd yours-wallet
bun install
bun run build

Loading in Chrome

1. Open chrome://extensions/
2. Enable Developer mode (toggle in the top right)
3. Click Load unpacked and select the build/ folder

WARNING: If you have the production Yours Wallet installed from the Chrome Web Store, disable it first. Running two instances simultaneously causes conflicts — duplicate popups, message collisions, and broken behavior. Toggle the store version off in chrome://extensions/ before loading your dev build.

After code changes, run bun run build again and click the reload icon on the extension card in chrome://extensions/.

Project Structure

src/
  ├── background.ts          # Service worker (wallet lifecycle, message handling)
  ├── initWallet.ts           # Wallet factory (createWebWallet, storage config)
  ├── pages/
  │   ├── BsvWallet.tsx       # Main wallet view (balances, send, receive)
  │   ├── OrdWallet.tsx       # Ordinals grid with selection modes
  │   ├── Settings.tsx        # Settings (identity, backup, accounts)
  │   └── StorageStatus.tsx   # Remote storage management UI
  ├── components/
  │   ├── BackupPromo.tsx     # Onboarding walkthrough (keys + backup)
  │   ├── ProviderPicker.tsx  # Known providers + custom remote entry
  │   └── AvatarPicker.tsx    # Profile image (upload or pick from ordinals)
  ├── hooks/
  │   ├── useIdentity.ts      # BAP identity (publish, update, inscribe avatar)
  │   └── useRemoteStatus.ts  # Live /account/status from known providers
  └── docs/
      └── remote-storage-provider.md  # Provider setup guide

Provider API

Integrate Yours Wallet into your dApp: Provider API Documentation

Covers connection, sending BSV, ordinals, tokens, MNEE, identity, locks, message signing, and marketplace operations. Working example app: test-1sat-sdk

Releases

Releases are built by GitHub Actions, never on a developer machine. Every tagged version ships as a reproducible zip with per-file checksums and a signed provenance attestation, so anyone can confirm that what is on the Chrome Web Store matches this source. See Releasing for how to cut a release and how to verify one.

Contributing

See CONTRIBUTING.md for guidelines.

Issues, Features, and PRs

Found a bug or want a feature? Fix it yourself with the help of an AI agent.

The Contributing with Agents guide gives AI coding assistants (Claude Code, Cursor, Copilot, etc.) the full context they need to understand the codebase, make changes, and submit a PR. Point your agent at that doc and describe what you want — it has the architecture, conventions, key files, and common patterns.

# Example: have your agent fix an issue
"Read docs/contributing-with-agents.md, then fix issue #123"

Or create an issue and the team will get to it.

Contact

• Email: support@bwalletx.com
• X: @bWalletX
• bChatX: bchatx.com
• YouTube: @bWalletX
• Website: bwalletx.com

License

MIT License