# Build apps with @bsv/simple

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

@bsv/simple is a TypeScript helper library on top of @bsv/sdk that gives a browser or server app one wallet object with methods for payments, tokens, data on chain, message box payments, identity and overlays.

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

Use `@bsv/simple` to add payments, tokens, data on chain and identity to a TypeScript app through one wallet object, in the browser or on a server. It is a helper library on top of `@bsv/sdk`. In the browser it wraps `WalletClient`, which talks to the user's BRC-100 (BSV Request for Comments 100, the standard interface between apps and wallets) wallet. On a server it wraps a `Wallet` from `@bsv/wallet-toolbox`. Each method builds the scripts and wallet calls for one common task. This page was written against `@bsv/simple` 0.7.2 and `@bsv/sdk` 4.0.1.

## When it fits your app

`@bsv/simple` fits an app whose tasks match its methods, such as sending a payment, creating a token or writing data on chain. Call `WalletClient` from `@bsv/sdk` directly when you need your own `createAction()` arguments, such as inputs or labels. The `pay()` method delivers a payment through a message box (A server that holds messages and payments for a recipient until the recipient collects them) and returns an empty `txid` with `@bsv/message-box-client` 2.7.0. To get the transaction ID of a payment, call `WalletClient` or use `sendDirectPayment()`, which returns it. You can also mix both, because `getClient()` returns the BRC-100 wallet under the object.

## Two entry points

The package has one entry point for each place your code runs. Both give a wallet object with the same methods:

<BlueTable>

| Entry point | Create the wallet with | Who holds the key | Use it for |
| --- | --- | --- | --- |
| `@bsv/simple/browser` | `createWallet()` | The user's wallet app, such as [BSV Desktop](https://bsvblockchain.com/docs/wallets/bsv-desktop/) or [BSV Browser](https://bsvblockchain.com/docs/wallets/bsv-browser/) | A web app where the user approves spending in their own wallet |
| `@bsv/simple/server` | `ServerWallet.create()` | Your server | A backend service or an agent that pays and signs on its own |

</BlueTable>

The package root, `@bsv/simple`, exports the same browser API plus the error classes, such as `WalletError`. Import `@bsv/simple/server` only in Node.js server code. In Node.js, the package needs version 22 or later.

> A server wallet signs every transaction with no one approving it, and a broadcast transaction cannot be undone. Keep its private key out of your repository. `ServerWallet.create()` uses Mainnet when you leave out `network`, so pass `network: 'testnet'` while you test. The default `storageUrl`, `https://storage.babbage.systems`, serves Mainnet, and the package has no testnet default, so also pass the address of a testnet storage server. [Run a wallet backend](https://bsvblockchain.com/docs/wallet-dev/infrastructure/) runs one on your machine with `BSV_NETWORK=test`.

## What it covers

The wallet object has these main methods:

<BlueTable>

| Task | Methods |
| --- | --- |
| Payments and balance | `send()`, `pay()`, `createPaymentRequest()`, `sendDirectPayment()`, `receiveDirectPayment()`, `getBalance()` |
| Tokens | `createToken()`, `listTokenDetails()`, `sendToken()`, `redeemToken()`, `sendTokenViaMessageBox()`, `listIncomingTokens()`, `acceptIncomingToken()` |
| Data on chain | `inscribeText()`, `inscribeJSON()`, `inscribeFileHash()`, `inscribeImageHash()` |
| Peer-to-peer payments and handles | Through a message box: `certifyForMessageBox()`, `sendMessageBoxPayment()`, `listIncomingPayments()`, `acceptIncomingPayment()`, `registerIdentityTag()`, `lookupIdentityByTag()` |
| Identity and certificates | For a DID (Decentralized identifier, a W3C identifier that the holder controls), certificates and credentials: `getDID()`, `resolveDID()`, `acquireCertificateFrom()`, `listCertificatesFrom()`, `relinquishCert()`, `acquireCredential()`, `listCredentials()` |
| Publishing and lookup | For overlay services (Services that track selected transactions and answer queries about them): `advertiseSHIP()`, `advertiseSLAP()`, `broadcastAction()`, `withRetry()` |

</BlueTable>

The package also exports classes that work without a wallet object: `DID` for `did:key` identifiers, `Certifier`, `CredentialSchema` and `CredentialIssuer` for certificates, and `Overlay` for overlay broadcast and lookup.

## Install the package

Install `@bsv/simple` with `@bsv/sdk`, its peer dependency:

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

The package also installs `@bsv/wallet-toolbox`, `@bsv/wallet-toolbox-client`, `@bsv/message-box-client` and `@bsv/did` as its own dependencies.

## Next steps

See how the package works, then use it in a guide:

- [How @bsv/simple is built](https://bsvblockchain.com/docs/sdk/simple/architecture/)
- [Store data and files](https://bsvblockchain.com/docs/guides/data-storage/)
- [Move your app to Mainnet](https://bsvblockchain.com/docs/guides/go-to-mainnet/)