# Start from the tipping sample

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

Run BSV Association's tipping sample on testnet: each user's wallet holds the keys, and a relay with no key passes tips to BSV Broadcaster.

import TippingFlow from '/snippets/TippingFlow.jsx';

The tipping sample is BSV Association's reference app for a user-side BRC-100 (The 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 enable` once, 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 with `npm install -g pnpm@11.22.0`. This guide was tested with Node.js 25.5.0 and pnpm 11.22.0.
- [BSV Desktop](https://desktop.bsvb.tech/) on testnet with free testnet coins. If you do not have it yet, follow [Set up a testnet wallet](https://bsvblockchain.com/docs/get-started/quick-start-browser/#set-up-a-testnet-wallet) and [Get free testnet coins](https://bsvblockchain.com/docs/get-started/quick-start-browser/#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](https://github.com/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:

<TippingFlow />

1. Tip, `createAction`: the tipper page picks a BRC-29 derivation for the creator and saves it in the browser. The tipper's wallet derives the creator's key, then signs and broadcasts the payment to it, with the tipper's approval when it asks.
2. Relay, `POST /api/tips`: the tipper page posts the transaction and the derivation to the relay. The relay checks the transaction against its BEEF and submits it to its own BSV Broadcaster endpoint, as EF. It holds no key.
3. Track, `GET /tx/TXID`: the relay reads the status from BSV Broadcaster and tells the creator page over server-sent events. BSV Broadcaster reports `SEEN_ON_NETWORK` or later, with no competing transaction.
4. Collect, `internalizeAction`: the creator page collects the tip once BSV Broadcaster has seen it, retrying after 10, 30 and 60 seconds. The creator's wallet derives 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`](https://github.com/bsv-blockchain/bsv-ai-toolkit/blob/main/samples/tipping-shape-a/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:

**1. Install and start the sample**

In the clone, install the dependencies from the root of the repository:

```bash
pnpm install
```

```text
Scope: all 5 workspace projects
Lockfile is up to date, resolution step is skipped
Packages: +331
...
Done in 8.1s using pnpm v11.22.0
```

Then 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:

```bash
cd samples/tipping-shape-a
cp env.example .env   # optional
pnpm dev
```

```text
[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:5173
```

The web app runs on port 5173 and the relay on port 8080. In a second terminal, check the relay:

```bash
curl -s http://localhost:8080/health
```

```text
{"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`.

**2. 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.

**3. 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 satoshis (The 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.

**4. 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 internalizeAction (The 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:

```bash
pnpm -F @bsv/mcp build
cd samples/tipping-shape-a
pnpm guardrails
```

The command prints the report as JSON and ends with this summary:

```text
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-38
```

Shape 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`](https://github.com/bsv-blockchain/bsv-ai-toolkit/blob/main/samples/tipping-shape-a/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](https://bsvblockchain.com/docs/build-with-ai/skill/) installed, point your agent at the sample, for example:

```text
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.
```

```text
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 Relay (An 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](https://bsvblockchain.com/docs/build-with-ai/skill/)
- [Connect your AI tool with MCP](https://bsvblockchain.com/docs/build-with-ai/mcp/)
- [Broadcast transactions with BSV Broadcaster](https://bsvblockchain.com/docs/guides/services/broadcasting/)