BSV blockchainBSV blockchain

Use the TypeScript SDK

Use @bsv/sdk to connect a TypeScript app to the user’s wallet, or to build keys, scripts and transactions yourself, in Node, in the browser or in a React app. It is the base library of the BSV blockchain TypeScript stack. @bsv/simple and @bsv/wallet-toolbox are built on it. It has no runtime dependencies. This page was written against @bsv/sdk 4.0.1.

To compare @bsv/sdk with the other packages before you choose, see the SDKs overview.

Two ways to use the SDK

An app uses the SDK in one of two ways, depending on who holds the private key:

TaskThrough the user’s walletBy hand
Hold the keys and signThe wallet, under the user’s controlYour code
Choose the coins and the feeThe walletYour code
Send the transaction to the networkThe walletYour code, with a broadcaster
Choose the networkThe walletYour code
Main classesWalletClientPrivateKey, Transaction, P2PKHPay to Public Key Hash, the standard script that locks coins to an address

Through the user’s wallet

WalletClient implements BRC-100BSV Request for Comments 100, the standard interface between apps and wallets on the app side. It finds a compatible wallet, such as BSV Desktop on the user’s computer, or BSV Browser on the phone, where the app runs inside the wallet’s browser. It calls methods such as createAction and getPublicKey on it. Your app never holds a private key, and the wallet asks the user to approve spends according to the permissions the user set. Most apps start here, and the Quick Start sends a first transaction this way.

By hand

Your code holds the key and does the work a wallet would do. It builds each locking scriptThe part of a transaction output that sets the condition to spend it and gives each input its source transaction. It also tracks which UTXOsUnspent transaction output it has already spent, since two transactions that spend the same output cannot both confirm. Build by hand when you need a custom script or transaction format, cryptography on its own, or SPVSimplified Payment Verification checks of transactions you receive.

When your code holds the private key, it signs with no approval step, and a transaction it broadcasts cannot be undone. Keep the key out of your source code and out of version control, and test on testnet before you use Mainnet.

What the SDK includes

The package covers both ways, from the wallet interface down to the primitives:

AreaMain classes
Wallet interfaceWalletClient to call a BRC-100 wallet, and ProtoWallet for key derivation, signatures and encryption without transactions
Keys and cryptographyPrivateKey, PublicKey, Hash, and KeyDeriver for BRC-42BSV Key Derivation Scheme key derivation
ScriptScript, and the templates P2PKH, PushDrop and RPuzzle
Transactions and feesTransaction and the SatoshisPerKilobyte fee model
ProofsBeef for BEEFBackground Evaluation Extended Format (BRC-62), a transaction sent with its proofs, MerklePath, and chain trackers such as WhatsOnChain
BroadcastingARC and Teranode
AuthenticationAuthFetch and Peer, for requests signed with the wallet’s identity key
Overlay servicesLookupResolver and TopicBroadcaster
File storageStorageUploader and StorageDownloader

Where it runs

In Node, @bsv/sdk needs Node.js 22 or newer. It is an ES module package that also ships a CommonJS build and a UMD bundle. Its TypeScript declarations cover both module formats, and it bundles for the browser with tools such as Vite.

Pages in this section

Start with the setup, then connect to the user’s wallet:

To build transactions yourself, start from Build transactions by hand, then go to the task you need:

To learn more about the TypeScript SDK on the BSV blockchain, review these articles: