# BSV for web developers

> Wallets, identity keys, signatures, BRCs and networks, explained by mapping each one to something you already know from web development.

> Agents: search these docs with the `search_docs` tool on the MCP server at https://createbsvapp.vercel.app/mcp, or read everything at https://createbsvapp.vercel.app/llms-full.txt.

You don't need to know how a blockchain works to use create-bsv-app. You *do* need five ideas, because they replace things you'd normally build yourself: user accounts, passwords and sessions.

## The cheat sheet

| You know | In a BSV app | Where it lives |
| --- | --- | --- |
| User ID | **identity key**, a public key like `02ab…` | the user's wallet |
| Password | a **signature** from the user's wallet | never sent, never stored |
| "Sign in with Google" | "Connect wallet" | `useWallet()` |
| Session cookie | a **proof** per request, or your own JWT after login | `signedFetch()`, `login()` |
| Server API key | the server's own identity key | `SERVER_PRIVATE_KEY` |
| Stripe checkout | a **transaction** the wallet creates | `wallet.createAction()` (not in the scaffold yet) |

## Wallets

A wallet is an app the user installs, such as [BSV Browser](https://browser.bsvb.tech/). It holds their private keys and **asks them before doing anything** with those keys. Your app never sees a private key. It asks the wallet to sign, encrypt or pay, and the wallet decides whether to.

**BRC-100** is the standard interface between apps and wallets, and `@bsv/sdk` exposes it as `WalletInterface`. Any BRC-100 wallet works with your app, on desktop or on a phone (paired by QR code).

## Identity keys

When a user connects, you get their **identity key**: a public key, 66 hex characters starting with `02` or `03`. It's stable for that wallet, it's unique, and nobody else can produce signatures for it. In practice it's your user ID.

::: warning There's no "forgot password"
If a user loses their wallet and has no backup, their identity is gone. Recovery is the wallet's job (backups, recovery phrases), not your app's. If your app needs account recovery, link identity keys to something you can verify another way, such as an email address.
:::

## Signatures vs transactions

This one trips people up:

- **A signature** proves "the owner of key X approved this exact message". It's free, instant, works offline and touches no blockchain. **Wallet login and signed requests are signatures.** That's why the scaffold costs nothing to run.
- **A transaction** moves coins and gets broadcast to the network. It costs a fee (on BSV, a tiny fraction of a cent) and is permanent. The scaffold doesn't create transactions *yet*. That's your next step.

### Your first payment

When you're ready, the connected `wallet` can create transactions. The user approves each one in their wallet:

```ts [client/src/pay.ts] twoslash
import { P2PKH, type WalletInterface } from '@bsv/sdk'

/** Ask the user's wallet to send `satoshis` to a BSV address. The wallet shows an approval prompt. */
export async function pay (wallet: WalletInterface, address: string, satoshis: number): Promise<string | undefined> {
  const { txid } = await wallet.createAction({
    description: 'Tip the author',
    outputs: [{
      lockingScript: new P2PKH().lock(address).toHex(),
      satoshis,
      outputDescription: 'Tip for the author'
    }]
  })
  return txid
}
```

```tsx
const { wallet } = useWallet()
if (wallet) await pay(wallet, recipientAddress, 1000) // 1000 satoshis
```

This type-checks against the `@bsv/sdk` version the scaffold installs. Try it on **testnet** first, with a testnet address and test coins from the [BSV Faucet](https://bsvfaucet.com/) (sign in, paste a testnet address, up to 10 million satoshis a day). Descriptions must be 5–50 characters, or the wallet rejects the action.

## Key derivation, briefly

A wallet doesn't sign everything with one key. For each purpose it derives a fresh key pair from the identity key, a **protocol**, a **key ID** and a **counterparty** (BRC-42 and BRC-43). That's how a login proof made *for your server* can't be replayed *against another server*: the counterparty is part of the key. The [testing guide](https://createbsvapp.vercel.app/docs/testing) proves it with a test.

::: note Privacy
The identity key itself is the same in every app the user connects to, so two apps can tell they're talking to the same wallet. Derived keys are different per protocol and counterparty, and that's where the privacy comes from.
:::

## Networks

| Network | `--network` | Coins | Use it for |
| --- | --- | --- | --- |
| Testnet | `test` (default) | free, worthless, from the [BSV Faucet](https://bsvfaucet.com/) | building and testing |
| Teratestnet | `ttn` | free, worthless | testing against Teranode, BSV's new node software |
| Mainnet | `main` | real | production |

Signatures work the same everywhere. The network only matters once you create transactions.

## BRCs you will meet

BRCs ("BSV Request for Comments") are BSV's open standards, published in the [BRCs repository](https://github.com/bitcoin-sv/BRCs).

| BRC | What it is | Where you'll see it |
| --- | --- | --- |
| BRC-100 | the app ↔ wallet interface | `WalletInterface`, `WalletClient` |
| BRC-103 | mutual authentication between peers | `@bsv/auth` proofs |
| BRC-42 / 43 | key derivation, protocol IDs and counterparties | every signature |
| BRC-52 | identity certificates (verified attributes on top of a key) | a future step for KYC-style needs |
| BRC-102 | deployment info (`deployment-info.json`) | the BRC-102 example starters |

## Overlays

Several [complete examples](https://createbsvapp.vercel.app/docs/starters#complete-examples) (Pollr, Postboard, MetaMarket and others) use **overlay services**: small servers that watch for transactions matching a topic and index them so apps can look them up. You don't need overlays for login or signed requests. They become relevant when your app's data lives *on chain*.

## Read next

::: cards
[**How the proof works** The four checks the server makes on every request.](https://createbsvapp.vercel.app/docs/capabilities#how-the-proof-works)

[**Security model** What's guaranteed, what isn't, and what to harden before launch.](https://createbsvapp.vercel.app/docs/security)
:::