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:
| Task | Through the user’s wallet | By hand |
|---|---|---|
| Hold the keys and sign | The wallet, under the user’s control | Your code |
| Choose the coins and the fee | The wallet | Your code |
| Send the transaction to the network | The wallet | Your code, with a broadcaster |
| Choose the network | The wallet | Your code |
| Main classes | WalletClient | PrivateKey, 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:
| Area | Main classes |
|---|---|
| Wallet interface | WalletClient to call a BRC-100 wallet, and ProtoWallet for key derivation, signatures and encryption without transactions |
| Keys and cryptography | PrivateKey, PublicKey, Hash, and KeyDeriver for BRC-42BSV Key Derivation Scheme key derivation |
| Script | Script, and the templates P2PKH, PushDrop and RPuzzle |
| Transactions and fees | Transaction and the SatoshisPerKilobyte fee model |
| Proofs | Beef for BEEFBackground Evaluation Extended Format (BRC-62), a transaction sent with its proofs, MerklePath, and chain trackers such as WhatsOnChain |
| Broadcasting | ARC and Teranode |
| Authentication | AuthFetch and Peer, for requests signed with the wallet’s identity key |
| Overlay services | LookupResolver and TopicBroadcaster |
| File storage | StorageUploader 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:
Install the SDK in Node or React
Add @bsv/sdk to a Node project, with ES modules or CommonJS, or to a React app.
Connect to a wallet with WalletClient
Connect to the user’s wallet and call its BRC-100 methods.
To build transactions yourself, start from Build transactions by hand, then go to the task you need:
Build a transaction from inputs and outputs
Create a transaction with inputs, outputs and script templates.
Derive HD keys with BIP32
Derive a tree of keys from one master key with the HD class, as BIP32 wallets do.
Write a custom script template
Write your own script template, with its locking and unlocking scripts.
Related articles
To learn more about the TypeScript SDK on the BSV blockchain, review these articles:
- How the BSV blockchain stack fits together
- BRC-100 Wallet Interface
- Broadcast transactions with BSV Broadcaster