BSV blockchainBSV blockchain

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 pointCreate the wallet withWho holds the keyUse it for
@bsv/simple/browsercreateWallet()The user’s wallet app, such as BSV Desktop or BSV BrowserA web app where the user approves spending in their own wallet
@bsv/simple/serverServerWallet.create()Your serverA 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:

TaskMethods
Payments and balancesend(), pay(), createPaymentRequest(), sendDirectPayment(), receiveDirectPayment(), getBalance()
TokenscreateToken(), listTokenDetails(), sendToken(), redeemToken(), sendTokenViaMessageBox(), listIncomingTokens(), acceptIncomingToken()
Data on chaininscribeText(), inscribeJSON(), inscribeFileHash(), inscribeImageHash()
Peer-to-peer payments and handlesThrough a message box: certifyForMessageBox(), sendMessageBoxPayment(), listIncomingPayments(), acceptIncomingPayment(), registerIdentityTag(), lookupIdentityByTag()
Identity and certificatesFor a DIDDecentralized identifier, a W3C identifier that the holder controls, certificates and credentials: getDID(), resolveDID(), acquireCertificateFrom(), listCertificatesFrom(), relinquishCert(), acquireCredential(), listCredentials()
Publishing and lookupFor 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/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: