--- name: bitcoinsv-design description: "Design and implementation guidance for BSV wallets, apps and payments, from the bitcoinsv.design guide. Routes to the right skill by what the user is doing or by BRC standard, and carries the patterns every BSV flow shares: payment states, loading labels, error messages, amounts in sats, counterparty display, fees, and confirmations before anything irreversible. Use this skill whenever building, reviewing or designing ANY BSV wallet, app, payment, permission prompt, backup flow or on-chain feature, even if the user only mentions 'BSV', 'Bitcoin SV', 'sats', 'BRC-100', 'Paymail', 'BEEF' or 'connect wallet'." --- > Agent index: · Every rule: · MCP: # bitcoinsv.design Guidance for designing and building on BSV: payments that pass directly between wallets and are accepted in seconds, fees that are less than a penny and not a decision, apps that ask a wallet to act instead of holding keys, tokens that are outputs a user holds, and data that can live on chain. Most of the design work is about being clear and honest about things that cannot be undone. **Base URL:** `https://www.bitcoinsv.design`. Paths below are relative to this file: fetch them from the same place, or read them from the same skills directory. ## Skills | Skill | Path | Use when | |---|---|---| | **Review a BSV product against the guide** | [`skills/bsv-design-review/SKILL.md`](skills/bsv-design-review/SKILL.md) | Review a screen, a flow or a diff against the guide, costly findings first, every one citing its rule. | | **Connect an app to a BSV wallet** | [`skills/bsv-wallet-connection/SKILL.md`](skills/bsv-wallet-connection/SKILL.md) | Connect, permissions, allowances, sign-in and Passes: the app's half of the conversation with a wallet. | | **Create, sign and report BSV actions** | [`skills/bsv-actions/SKILL.md`](skills/bsv-actions/SKILL.md) | createAction, signAction, abortAction and listActions, with descriptions people can read and states that tell the truth. | | **Send and receive BSV payments** | [`skills/bsv-payments/SKILL.md`](skills/bsv-payments/SKILL.md) | Paying a person, getting paid, and the review screen that is the last chance to catch a mistake. | | **Charge per use with BSV micropayments** | [`skills/bsv-micropayments/SKILL.md`](skills/bsv-micropayments/SKILL.md) | Prices of a few sats, payment inside the request, and a running total the user can always see and stop. | | **Let software spend BSV on someone's behalf** | [`skills/bsv-agent-spending/SKILL.md`](skills/bsv-agent-spending/SKILL.md) | A wallet of its own, limits it cannot argue with, and a report a person actually reads. | | **Show, receive and issue BSV tokens** | [`skills/bsv-tokens/SKILL.md`](skills/bsv-tokens/SKILL.md) | A token is an output you hold. Show what it is, where it came from, and whether it is the real one. | | **Write data on the BSV chain with consent** | [`skills/bsv-on-chain-data/SKILL.md`](skills/bsv-on-chain-data/SKILL.md) | Hash by default, say "permanent and public" before writing, and never offer a delete button. | | **Lock BSV behind keys, time or a secret** | [`skills/bsv-script-conditions/SKILL.md`](skills/bsv-script-conditions/SKILL.md) | Multi-key, time locks with nLockTime and nSequence, and the configuration that has to be backed up with the keys. | | **Write BSV amounts, units and interface copy** | [`skills/bsv-amounts-and-copy/SKILL.md`](skills/bsv-amounts-and-copy/SKILL.md) | Units, formatting and the words on screen, where an amount off by a factor of a hundred million is a design bug. | | **Design BSV wallet backup and recovery** | [`skills/bsv-backup-and-recovery/SKILL.md`](skills/bsv-backup-and-recovery/SKILL.md) | The two halves of a BSV backup, the flow that gets both done, and a restore that says what came back. | ## Routing guide Match the task to a skill, then read that skill's `SKILL.md`. ### By what the user is doing - Reviewing a screen, a flow or a diff before it ships → [bsv-design-review](skills/bsv-design-review/SKILL.md) - App connects to a wallet for the first time → [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md) - App asks for a permission or a spending allowance → [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md) - User signs in with their wallet → [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md) - App asks for proof of an attribute (a Pass) → [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md) - User reviews or revokes what an app can do → [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md) - App creates or signs a transaction → [bsv-actions](skills/bsv-actions/SKILL.md) - A pending action is cancelled → [bsv-actions](skills/bsv-actions/SKILL.md) - Showing whether something worked → [bsv-actions](skills/bsv-actions/SKILL.md) - User sends to a contact or a handle → [bsv-payments](skills/bsv-payments/SKILL.md) - User pastes or scans an address → [bsv-payments](skills/bsv-payments/SKILL.md) - User receives a payment → [bsv-payments](skills/bsv-payments/SKILL.md) - User asks somebody to pay them → [bsv-payments](skills/bsv-payments/SKILL.md) - App charges per article, request or minute → [bsv-micropayments](skills/bsv-micropayments/SKILL.md) - User sees what they have spent with an app → [bsv-micropayments](skills/bsv-micropayments/SKILL.md) - User stops paying an app → [bsv-micropayments](skills/bsv-micropayments/SKILL.md) - An agent or automated tool spends on somebody's behalf → [bsv-agent-spending](skills/bsv-agent-spending/SKILL.md) - User holds, receives or transfers a token → [bsv-tokens](skills/bsv-tokens/SKILL.md) - Product issues a token or a stablecoin → [bsv-tokens](skills/bsv-tokens/SKILL.md) - App writes a hash, a record or a file on chain → [bsv-on-chain-data](skills/bsv-on-chain-data/SKILL.md) - App proves when something existed → [bsv-on-chain-data](skills/bsv-on-chain-data/SKILL.md) - Product locks money behind several keys → [bsv-script-conditions](skills/bsv-script-conditions/SKILL.md) - Money should not move before a date, or opens to somebody after one → [bsv-script-conditions](skills/bsv-script-conditions/SKILL.md) - User sets up inheritance or recovery after inactivity → [bsv-script-conditions](skills/bsv-script-conditions/SKILL.md) - Writing any amount, label or string a user will read → [bsv-amounts-and-copy](skills/bsv-amounts-and-copy/SKILL.md) - User backs up a wallet → [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) - User recovers a wallet on a new device → [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) ### By standard | Standard | What it is | Skill | |---|---|---| | BRC-22 | Overlay services: indexing the on-chain data an app cares about | [bsv-on-chain-data](skills/bsv-on-chain-data/SKILL.md) | | BRC-29 | Peer-to-peer payments | [bsv-payments](skills/bsv-payments/SKILL.md), [bsv-micropayments](skills/bsv-micropayments/SKILL.md) | | BRC-38 | The wallet data format: the records half of a backup | [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) | | BRC-39 | Encryption for the wallet data format | [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) | | BRC-42 | Key derivation: a fresh key for every payment | [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md), [bsv-payments](skills/bsv-payments/SKILL.md), [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) | | BRC-43 | The invoice numbers that drive key derivation | [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md), [bsv-payments](skills/bsv-payments/SKILL.md) | | BRC-52 | Identity certificates, shown to users as Passes | [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md) | | BRC-62 | BEEF: a transaction packaged with the proofs to check it | [bsv-actions](skills/bsv-actions/SKILL.md), [bsv-payments](skills/bsv-payments/SKILL.md) | | BRC-69 | Key linkage revelation, for audits | [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md) | | BRC-74 | Merkle paths inside BEEF | [bsv-actions](skills/bsv-actions/SKILL.md), [bsv-payments](skills/bsv-payments/SKILL.md) | | BRC-75 | Recovery words | [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) | | BRC-100 | The Wallet Application Interface: how an app asks a wallet for anything | [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md), [bsv-actions](skills/bsv-actions/SKILL.md), [bsv-micropayments](skills/bsv-micropayments/SKILL.md), [bsv-agent-spending](skills/bsv-agent-spending/SKILL.md), [bsv-script-conditions](skills/bsv-script-conditions/SKILL.md) | | BRC-121 | HTTP 402: payment inside a web request | [bsv-micropayments](skills/bsv-micropayments/SKILL.md) | | BRC-140 | Splitting a key into shares with a threshold | [bsv-script-conditions](skills/bsv-script-conditions/SKILL.md), [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) | | BRC-147 | Token basket profiles | [bsv-tokens](skills/bsv-tokens/SKILL.md) | | BRC-151 | The risk assessment behind the wallet interface's guardrails | [bsv-wallet-connection](skills/bsv-wallet-connection/SKILL.md), [bsv-agent-spending](skills/bsv-agent-spending/SKILL.md) | | BRC-154 | A key share held by a service | [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) | | BRC-157 | Recovery words that also split into shares | [bsv-backup-and-recovery](skills/bsv-backup-and-recovery/SKILL.md) | | BRC-159 | 1Sat Ordinals | [bsv-tokens](skills/bsv-tokens/SKILL.md) | | BRC-160 | 1Sat Ordinals inscriptions | [bsv-tokens](skills/bsv-tokens/SKILL.md) | | BRC-161 | BSV-21 fungible tokens | [bsv-tokens](skills/bsv-tokens/SKILL.md) | | BRC-163 | Token basket profiles | [bsv-tokens](skills/bsv-tokens/SKILL.md) | | BRC-165 | Basket permissions | [bsv-tokens](skills/bsv-tokens/SKILL.md) | | BRC-168 | Timestamps from blocks | [bsv-on-chain-data](skills/bsv-on-chain-data/SKILL.md) | | BRC-169 | Handles | [bsv-payments](skills/bsv-payments/SKILL.md) | | BRC-176 | BSV-21 validity proofs | [bsv-tokens](skills/bsv-tokens/SKILL.md) | | BRC-220 | Notarisation: proving a document existed | [bsv-on-chain-data](skills/bsv-on-chain-data/SKILL.md) | | BRC-224 | Carrying large media across transactions | [bsv-on-chain-data](skills/bsv-on-chain-data/SKILL.md) | ### Shared reference [`skills/bitcoinsv-design/references/shared-patterns.md`](skills/bitcoinsv-design/references/shared-patterns.md): payment states, loading labels, errors, amounts, who is on the other end, fees, and irreversible actions. Load it for any flow that moves money. ## What you do not have to design Most of what makes a payments interface hard is absent on BSV. Design for what is here, not for what other systems need: - **No fee decisions.** A fee is less than 1p: no picker, no estimate, no bumping, no stuck state. ([Send fees](https://www.bitcoinsv.design/guide/daily-spending-wallet/sending/send-fees/)) - **No waiting on blocks for everyday amounts.** The recipient's wallet verifies and accepts the payment on handover, and miners keep the first valid version they see. ([Transactions](https://www.bitcoinsv.design/guide/how-it-works/transactions/)) - **No keys in the app.** An app asks the user's wallet to act and only sees results. ([Connecting a wallet](https://www.bitcoinsv.design/guide/patterns/connecting-a-wallet/)) - **No approvals to grant or revoke for tokens.** A token is an output the user holds, kept in its own basket. ([Holding tokens](https://www.bitcoinsv.design/guide/patterns/holding-tokens/)) - **No minimum worth paying.** A payment of a few satoshis is ordinary, so charging per use is practical. ([Charging per use](https://www.bitcoinsv.design/guide/patterns/charging-per-use/)) What is left is mostly about honesty with things that cannot be undone: the recipient, the network, the backup, and anything written on chain. ## Live lookups - `https://www.bitcoinsv.design/api/rules.json`: every rule, most costly first, each with a citation URL. - `https://www.bitcoinsv.design/mcp/`: `search_guide`, `read_page`, `list_sections`, `list_rules`. - `https://www.bitcoinsv.design/llms-full.txt`: the whole guide as markdown. ## Implementation resources - **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk. - **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app. - **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number. --- _Generated from https://www.bitcoinsv.design/, Open BSV License Version 6._