SDKs overview
Use the BSV blockchain SDKs to create keys and transactions, or to call a user’s wallet, from your own code in TypeScript, Go or Python. A Rust SDK is in development. The samples in the chooser create a key and print a testnet address, so you can run them without funds. If you have not sent a payment yet, start with Send a payment from a web app.
Choose your SDK
Every sample creates a random private key. Treat it as a throwaway testnet key: never reuse it, and never paste a real key into the script.
Which language do you use?
@bsv/sdk is the base library of the TypeScript stack. Ask the user's wallet to sign through WalletClient, or build keys, scripts and transactions yourself, in Node, the browser or React.
Install
npm install @bsv/sdkCreate a key and print its testnet address
import { PrivateKey } from '@bsv/sdk'
const key = PrivateKey.fromRandom()
console.log(key.toPublicKey().toAddress('testnet'))Output
A testnet address that starts with m or n.
Tested with @bsv/sdk 4.0.1.
See each package in code
Your app asks a local BRC-100The standard interface between an app and a wallet wallet, such as BSV Desktop or BSV Browser, to do the work, and @bsv/sdk is the place to start. Through WalletClient, the app finds the wallet on the user’s machine, and the wallet keeps the keys and asks the user to approve each spend.
import { WalletClient } from '@bsv/sdk'
// The second value is the name of your app, shown in the wallet's prompts
const wallet = new WalletClient('auto', 'example.com')
console.log(await wallet.getNetwork())Sample output #
{ network: 'testnet' }The @bsv/simple/browser package offers shortcuts for payments and tokens, such as pay() and createToken(), on top of these wallet calls. In version 0.7.0, pay() returns an empty txid, and createWallet() reports the network as main whatever network the wallet is on. To get the transaction ID, use createAction on WalletClient, and to read the network, use getNetwork().
If you come from another chain, use @bsv/wallet-helper (beta) to describe outputs, scripts and change explicitly while the wallet still holds the keys and signs. It runs in the browser and in Node.
import { WalletClient } from '@bsv/sdk'
import { TransactionBuilder } from '@bsv/wallet-helper'
const recipientAddress = '<testnet address>'
const wallet = new WalletClient('auto', 'example.com')
const { txid } = await new TransactionBuilder(wallet, 'Pay a testnet address')
.addP2PKHOutput({ address: recipientAddress, satoshis: 1000 })
.build()
console.log(txid)Sample output #
1713a693288b5f9669ee48ca6fc471156e2d5dc6f9d47131f8a77610bb8d4dafThe wallet asks the user to approve the spend before the transaction ID prints.
A service, bot or test harness that owns its key, with no person approving each transaction, starts from @bsv/simple/server. The server entry point is part of the @bsv/simple package, so install that package:
npm install @bsv/simpleimport { ServerWallet } from '@bsv/simple/server'
const wallet = await ServerWallet.create({
privateKey: process.env.SERVER_PRIVATE_KEY!,
network: 'testnet',
storageUrl: 'https://go-wallet-testnet-us-1.bsvblockchain.tech'
})
console.log(await wallet.getBalance())Sample output #
{
totalSatoshis: 0,
totalOutputs: 0,
spendableSatoshis: 0,
spendableOutputs: 0
}The storageUrl above is a testnet storage server for the BSV blockchain. The public Wallet Infra endpoints, such as store-us-1.bsvb.tech, store-eu-1.bsvb.tech and store-ap-1.bsvb.tech, store Mainnet wallets, so on testnet use that server or your own deployment.
Keep wallet storage local when you can, with Setup.createWalletSQLite from @bsv/wallet-toolbox.
Implementing a wallet, extending its storage, building permission screens, or porting the wallet model to another language starts from @bsv/wallet-toolbox. The package ships the reference pieces: Wallet, WalletStorageManager, storage providers, WalletSigner, Services, Monitor, key managers, permissions, and test utilities such as MockChain. The BRC-100 Wallet Interface page explains the boundary between an app and a wallet.
import { PrivateKey } from '@bsv/sdk'
import { Setup } from '@bsv/wallet-toolbox'
const key = PrivateKey.fromRandom()
const identityKey = key.toPublicKey().toString()
const { wallet } = await Setup.createWalletSQLite({
env: {
chain: 'test',
identityKey,
identityKey2: identityKey,
filePath: 'wallet.sqlite',
taalApiKey: '',
devKeys: { [identityKey]: key.toHex() }
},
rootKeyHex: key.toHex(),
filePath: 'wallet.sqlite',
databaseName: 'my-wallet'
})
console.log(await wallet.getNetwork())Sample output #
{ network: 'testnet' }An ordinary web app, or a backend agent with a private key, starts from one of the first three tabs.
Code that works with the primitives themselves, with nothing built on top of them, uses @bsv/sdk directly. It covers secp256k1 and secp256r1 cryptography, hashing, Script, transactions, BEEFBackground Evaluation Extended Format, a transaction sent with its proofs (BRC-62), Merkle paths (BRC-74), BRC-42 key derivation, ARC broadcasting, and the BRC-100 interface types with wallet substrates.
import { PrivateKey, P2PKH } from '@bsv/sdk'
const key = PrivateKey.fromRandom()
const address = key.toPublicKey().toAddress()
console.log(address, new P2PKH().lock(address).toASM())Sample output #
1AB4wscnziNS6euaxcF39VrWW77SZh485A OP_DUP OP_HASH160 64a095f0148483a9c603de9255bd98ce066f3ab6 OP_EQUALVERIFY OP_CHECKSIGServices and packages for other jobs
Some pieces are shared services you run or connect to, not packages you install:
| Service | What it does |
|---|---|
| Wallet Infra | JSON-RPC storage and management of wallet UTXOs |
| Message Box Server | Peer-to-peer messaging with real-time WebSocket delivery |
| Overlay Server | Topic managers and lookup services for an overlay network |
| UHRP Server | Production file storage on Google Cloud, addressed by content with UHRPUniversal Hash Resolution Protocol |
| Wallet Abstraction Backend (WAB) | Multi-factor user authentication and key recovery, with SMS, ID verification and one-time codes |
| Chaintracks Server | ChaintracksThe reference implementation for managing the block headers of the BSV blockchain keeps the block header chain and validates Merkle roots over REST |
For work beyond the starting points above, add the package built for it:
| You are building | Add |
|---|---|
| Messaging between users | @bsv/message-box-client with a Message Box Server |
| A token system | @bsv/btms and @bsv/btms-permission-module |
| An overlay node | @bsv/overlay and @bsv/overlay-express |
| An authenticated API | @bsv/auth-express-middleware |
| A payment-gated API | @bsv/402-pay (beta), set up in Gate an API Behind Payments |
| File storage | @bsv/overlay-topics (experimental) with a UHRP Server |
Related articles
To learn more about the SDKs on the BSV blockchain, review these articles: