Start from the tipping sample
The tipping sample is BSV Association’s reference app for a user-side BRC-100The standard interface between an app and a wallet wallet: each user’s wallet holds the keys, and a small relay with no key passes each tip to BSV Broadcaster (formerly Arcade). Use it when you want a working app for your agent to copy or adapt, one that already passes the BSV blockchain guardrails. At the end, the sample runs on your machine on testnet, and a tip has gone from one wallet to another.
Before you begin
- Node.js 22.9 or newer.
- pnpm. Run
corepack enableonce, and corepack picks the pnpm version the repository pins. On Node.js 25 and newer, which no longer include corepack, or wherever corepack is missing, install pnpm withnpm install -g pnpm@11.22.0. This guide was tested with Node.js 25.5.0 and pnpm 11.22.0. - BSV Desktop on testnet with free testnet coins. If you do not have it yet, follow Set up a testnet wallet and Get free testnet coins in the web app guide.
- Two wallet identities, one for the creator and one for the tipper: two browser profiles, each connected to a different wallet, or two wallets.
- A clone of bsv-blockchain/bsv-ai-toolkit, where the sample is in
samples/tipping-shape-a.
How it works
A tip goes from the tipper’s wallet through the relay to BSV Broadcaster, and the creator’s wallet collects it:
Tip
createActionTipper pagePicks a BRC-29 derivation for the creator and saves it in the browser.
Tipper's walletDerives the creator's key, then signs and broadcasts the payment to it, with the tipper's approval when it asks.
Relay
POST /api/tipsTipper pagePosts the transaction and the derivation to the relay.
RelayChecks the transaction against its BEEF and submits it to its own BSV Broadcaster endpoint, as EF. It holds no key.
Track
GET /tx/TXIDRelayReads the status and tells the creator page over server-sent events.
BSV BroadcasterReports SEEN_ON_NETWORK or later, with no competing transaction.
Collect
internalizeActionCreator pageCollects the tip once BSV Broadcaster has seen it, retrying after 10, 30 and 60 seconds.
Creator's walletDerives the key from the derivation, and adds the tip only if it is its own.
The wallet shows the app under its origin and reads the app’s permissions from manifest.json there. The relay cannot spend, redirect or forge a tip. TRUST.md in the sample states what users trust and the risks that remain.
Run the sample
Install the sample, then tip from one wallet to the other:
Install and start the sample
In the clone, install the dependencies from the root of the repository:
pnpm installScope: all 5 workspace projects
Lockfile is up to date, resolution step is skipped
Packages: +331
...
Done in 8.1s using pnpm v11.22.0Then start the sample from its folder. Without a .env, it runs on testnet with the public testnet BSV Broadcaster endpoint. To change a setting, copy env.example to .env first, since pnpm dev reads .env when it exists:
cd samples/tipping-shape-a
cp env.example .env # optional
pnpm dev[web] VITE v7.3.7 ready in 677 ms
[web]
[web] ➜ Local: http://localhost:5173/
[web] ➜ Network: use --host to expose
[relay] bsv-tipping-demo relay on :8080 network=testnet broadcaster=https://arcade-v2-testnet-us-1.bsvblockchain.tech origin=http://localhost:5173The web app runs on port 5173 and the relay on port 8080. In a second terminal, check the relay:
curl -s http://localhost:8080/health{"ok":true,"network":"testnet","broadcasterOrigin":"https://arcade-v2-testnet-us-1.bsvblockchain.tech","version":"0.1.0"}The relay is on testnet and uses the public testnet BSV Broadcaster endpoint, whose hostname still contains arcade.
Open the creator page
In the browser profile of the creator, open http://localhost:5173/creator and click Connect wallet. At this first connection, the page asks the wallet once for the permissions the app lists in its manifest.json.
The first wallet that claims this page becomes the creator. To choose the creator yourself, set CREATOR_IDENTITY_KEY in .env to the identity key of the creator’s wallet. The page collects tips only while it is open, so keep it open.
Send a tip
In the browser profile of the tipper, open http://localhost:5173/ and click Connect wallet. Enter an amount of at least 546 satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV, click Tip, check the summary and click Send tip.
The page asks the wallet for the payment. The wallet adds the network fee, and it can ask you to approve the payment. A sent payment cannot be undone, so check the amount before you approve.
Watch the tip arrive
On the creator page, the tip appears once BSV Broadcaster has seen it, usually within a few seconds, and shows as seen on network. If BSV Broadcaster takes longer, it shows as pending first. The page then collects it with internalizeActionThe BRC-100 wallet call that takes a transaction paid to the wallet and adds its outputs to the balance, and the tip shows as received.
The app does not wait for the transaction to be mined. At SEEN_ON_NETWORK or later with no competing transaction, a payment of this size is final for the app.
Check it against the guardrails
The sample reports zero errors in the guardrail check. In Claude Code with @bsv/mcp connected, ask Check samples/tipping-shape-a against the BSV guardrails., or run the check from the terminal. Build @bsv/mcp once at the root of the repository, then run the check in the sample folder:
pnpm -F @bsv/mcp build
cd samples/tipping-shape-a
pnpm guardrailsThe command prints the report as JSON and ends with this summary:
check_guardrails: 0 errors, 0 warnings, shape A+B
passed: G-01, G-02, G-03, G-04, G-06, G-08, G-09, G-10, G-12, G-14, G-15, G-16, G-21, G-25, G-31, G-34
not applicable: G-36
manual checklist: G-05, G-07, G-11, G-13, G-17, G-18, G-19, G-20, G-22, G-23, G-24, G-26, G-27, G-28, G-29, G-30, G-32, G-33, G-35, G-37, G-38Shape A means that the user’s own wallet holds the keys, and shape B means a server wallet that the app runs. The report says shape A+B because the sample’s testnet gate, a test script, uses @bsv/wallet-toolbox for its headless test wallets. The app itself is shape A. G-36, the lock-time rule, does not apply, since the sample sets no lock time. GUARDRAILS.md maps each guardrail that applies to the file that meets it, including the manual ones.
Ask your agent to adapt it
With the BSV blockchain agent skill installed, point your agent at the sample, for example:
Read samples/tipping-shape-a in bsv-blockchain/bsv-ai-toolkit, then add the same tipping flow to my React app on BSV, on testnet.Change the tipping sample to a fixed tip of 1,000 satoshis, then run check_guardrails and fix every error.The skill tells the agent to keep the same defaults as the sample: testnet, the user’s wallet for every key, and BSV Broadcaster for every broadcast and status read. For a new app, it also adds a login with a phone wallet over Wallet RelayAn encrypted connection between a web app and a phone wallet, paired by QR code, which the sample does not have.
Next steps
With the sample running, give your agent the tools it uses, or read how the relay broadcasts:
- Install the BSV blockchain agent skill
- Connect your AI tool with MCP
- Broadcast transactions with BSV Broadcaster