# Connect to a browser wallet

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

createWallet from @bsv/simple/browser connects a web page to the user's BRC-100 wallet and returns an object with methods for payments, tokens and data.

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

Connect a web page to [BSV Desktop](https://bsvblockchain.com/docs/wallets/bsv-desktop/) with `createWallet` from `@bsv/simple/browser`, then read the wallet's identity key (The public key that identifies a wallet to apps and other users), network and balance. Do this first in a web app where each user approves spending in their own wallet, before you call the payment, token or data methods of `@bsv/simple`. The example is a page of its own, served by Vite, and its calls read the wallet without spending. This page was written against `@bsv/simple` 0.7.2, `@bsv/sdk` 4.0.1 and Vite 8.3.8.

## Before you begin

You need:

- Node.js 22.12 or newer, which Vite 8 requires.
- A Vite project. To create one, run `npm create vite@latest my-app -- --template vanilla --no-interactive`. It ends with `Done. Now run:` and the next commands. Then install the packages in the `my-app` folder:

  ```bash
  npm install @bsv/simple @bsv/sdk
  ```

  The install ends with:

  ```text
  added 173 packages, and audited 174 packages in 1m

  found 0 vulnerabilities
  ```

- BSV Desktop open and set to testnet. To set it up, follow [Set up a testnet wallet](https://bsvblockchain.com/docs/get-started/quick-start-browser/#set-up-a-testnet-wallet) in the Quick Start.

## How it works

`createWallet` creates a `WalletClient` from `@bsv/sdk` with the `'auto'` substrate (The transport between your code and the wallet, such as the HTTP port of BSV Desktop), which finds the wallet running on the user's machine, and asks it for the user's identity key. It then returns a wallet object that holds the key and the `@bsv/simple` methods. The page holds no private key: every method that spends or signs goes to the wallet, which can ask the user to approve it. A payment the user approves is broadcast and cannot be reversed. To see how the package wraps `@bsv/sdk`, read [How @bsv/simple is built](https://bsvblockchain.com/docs/sdk/simple/architecture/). To see how the substrates and the origin work, read [Connect to a wallet with WalletClient](https://bsvblockchain.com/docs/sdk/typescript/wallet-client/).

`createWallet` takes an optional object of defaults for the wallet object's methods. The main ones:

<BlueTable>

| Default | Value when left out | Used for |
| --- | --- | --- |
| `network` | `'main'` | The `network` field that `getStatus()` and `getWalletInfo()` return |
| `description` | `'BSV-Simplify transaction'` | The description of the transactions that `send()` and the inscription methods create |
| `outputDescription` | `'BSV-Simplify output'` | The description of the outputs of those transactions |
| `tokenBasket` | `'tokens'` | The basket (A named group of outputs that a wallet tracks together) where the token methods keep tokens |
| `messageBoxHost` | `'https://messagebox.babbage.systems'` | The message box server that `pay()` uses |

</BlueTable>

The wallet decides the network, not the `network` default. Pass `network: 'testnet'` so that `getStatus()` reports the network you test on, and read the network of the wallet itself with `getClient().getNetwork()`.

## Connect from a web page

The first step is a page with one button that starts the connection. In the `my-app` folder:

> `getAddress()` returns the address of the identity key in the Mainnet format, which starts with `1`, even when the wallet is on testnet. Do not show it to users as a testnet address, and do not ask anyone to send coins to it. To receive a payment, use the payment methods of `@bsv/simple` instead.

**1. Add the button**

Replace the content of `index.html` with a button, an area for the results and the script of the page:

```html index.html
<!doctype html>
<html lang="en">
  <head><meta charset="utf-8"><title>Browser wallet</title></head>
  <body>
    <button id="connect">Connect wallet</button>
    <pre id="out"></pre>
    <script type="module" src="/main.js"></script>
  </body>
</html>
```

**2. Write the script**

Create `main.js` next to `index.html`. On a click, it connects to the wallet and writes five values on the page:

```javascript main.js
import { createWallet } from '@bsv/simple/browser'

const out = document.getElementById('out')
const log = (line) => { out.textContent += line + '\n' }

document.getElementById('connect').addEventListener('click', async () => {
  try {
    const wallet = await createWallet({ network: 'testnet' })
    log('Identity key: ' + wallet.getIdentityKey())
    log('Status: ' + JSON.stringify(wallet.getStatus()))
    log('Address: ' + wallet.getAddress())
    const { network } = await wallet.getClient().getNetwork()
    log('Wallet network: ' + network)
    const balance = await wallet.getBalance()
    log('Balance: ' + JSON.stringify(balance))
  } catch (e) {
    log('Error: ' + e.message)
  }
})
```

- `getIdentityKey()` returns the public identity key that `createWallet` received from the wallet. It identifies the user to other apps and is safe to share.
- `getClient()` returns the `WalletClient` under the object, so you can call any BRC-100 (The standard set of methods an app calls on a user's wallet) method that `@bsv/simple` does not wrap, such as `getNetwork`.
- `getBalance()` with no basket returns the balance of the wallet's default basket in `totalSatoshis` and `spendableSatoshis`, and `0` in the two output counts. Pass a basket name, such as `getBalance('tokens')`, to count the outputs of that basket too.

**3. Start the page**

Run the Vite development server from the `my-app` folder:

```bash
npx vite --port 5173
```

Vite prints the address of the page. Your startup time differs:

```text
VITE v8.3.8  ready in 209 ms

➜  Local:   http://localhost:5173/
```

Open that address in the browser, with BSV Desktop open.

**4. Connect the wallet**

Click **Connect wallet**. If BSV Desktop asks whether the page may use the wallet, approve it. The page then shows the five values. Your key, address and balance differ. `YOUR_IDENTITY_KEY` and `YOUR_ADDRESS` stand for the 66 character key and the address of your wallet:

```text
Identity key: YOUR_IDENTITY_KEY
Status: {"isConnected":true,"identityKey":"YOUR_IDENTITY_KEY","network":"testnet"}
Address: YOUR_ADDRESS
Wallet network: testnet
Balance: {"totalSatoshis":985000,"totalOutputs":0,"spendableSatoshis":985000,"spendableOutputs":0}
```

The `Wallet network` line comes from BSV Desktop, so the page runs on testnet.

Each call to `createWallet` creates a new `WalletClient` and asks the wallet for the identity key again, so an app keeps one wallet object and calls `pay()` or `getBalance()` on it.

## Next steps

With the page connected, use the wallet object in a guide, then look up its methods:

- [Store data and files](https://bsvblockchain.com/docs/guides/data-storage/)
- [BrowserWallet class](https://bsvblockchain.com/docs/sdk/api/simple/browser-wallet/)