Build apps with @bsv/simple
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-100BSV 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 boxA 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:
| 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 or 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 |
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 runs one on your machine with BSV_NETWORK=test.
What it covers
The wallet object has these main methods:
| 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 DIDDecentralized identifier, a W3C identifier that the holder controls, certificates and credentials: getDID(), resolveDID(), acquireCertificateFrom(), listCertificatesFrom(), relinquishCert(), acquireCredential(), listCredentials() |
| Publishing and lookup | For overlay servicesServices that track selected transactions and answer queries about them: advertiseSHIP(), advertiseSLAP(), broadcastAction(), withRetry() |
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:
npm install @bsv/simple @bsv/sdkThe 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: