Getting Started with @bsv/sdk: Installation, Verification, and First Steps

In a Nutshell

@bsv/sdk is one of the main entry points for developing BSV applications in TypeScript, encapsulating transactions, scripts, wallet connections, and common protocol capabilities into callable code.

If you previously only understood "what a transaction is," now you will start writing code hands-on. The significance of installing the SDK is not just making the project run, but also placing abstract concepts into a real development environment: you will see how objects like WalletClient, Script, createAction(), transaction IDs, and block explorers connect together.

What to Prepare First

Before starting, you need three basic prerequisites:

Install Node.js — Beginners don’t need to study all details of Node.js at first; just know it runs JavaScript and TypeScript projects.
Set up a TypeScript project — The official BSV SDK tutorials use TypeScript examples; it’s recommended to start with TypeScript rather than plain JavaScript.
Prepare a wallet that can communicate with your app — The official first transaction tutorial assumes a wallet that complies with the BRC-100 wallet interface (e.g., a local desktop wallet). Without a wallet, the SDK can still be imported, but you cannot complete real transactions that require signing and funds.

What a Minimal Project Looks Like

Start from an empty directory:

Shell

1mkdir my-first-bsv-tx

2cd my-first-bsv-tx

3npm init -y

4npm install typescript ts-node @types/node --save-dev

5npm install @bsv/sdk

These commands do several things:

npm init -y creates package.json, the basic descriptor file for a Node.js project.
typescript provides TypeScript compilation capabilities.
ts-node allows you to directly run .ts files, suitable for quick verification in the early stages.
@types/node provides Node.js type definitions so that TypeScript can recognize Node.js objects like Buffer.
@bsv/sdk is the actual BSV SDK you will use at this stage.

Then create a minimal tsconfig.json:

JSON

2 "compilerOptions": {

3 "target": "es2020",

4 "module": "commonjs",

5 "esModuleInterop": true,

6 "strict": true,

7 "outDir": "./dist"

8 }

This is not the only configuration, but it’s sufficient for the first transaction tutorial. For beginners, it’s recommended not to focus on build tools; getting the transaction code running is more important.

Verify the Import After Installation

Create a new file check-sdk.ts:

TYPESCRIPT

1import { WalletClient, Script } from '@bsv/sdk'

3console.log(typeof WalletClient)

4console.log(typeof Script.fromASM)

Run:

Shell

1npx ts-node check-sdk.ts

If you don’t get 'Cannot find module' errors, syntax errors, or TypeScript configuration errors, it means the project can import the SDK.

Note: This step only verifies that the SDK can be loaded into the project; it does not mean the wallet is successfully connected, nor that you can broadcast transactions.

Position in the BSV Tech Stack

@bsv/sdk sits at the application development entry point in the BSV tech stack.

The underlying protocol concerns inputs, outputs, locking scripts, unlocking scripts, serialization, signing, and broadcast. The SDK organizes these capabilities into objects and methods that developers can call.

At this stage, we use the SDK’s high-level interfaces to first establish a complete chain:

Code

1TypeScript code

2 -> WalletClient

3 -> Wallet authorization and signing

4 -> createAction()

5 -> Transaction broadcast

6 -> txid

7 -> View on block explorer

Once this chain is working, learning to construct transactions manually (Stage 8) will be more stable. Otherwise, beginners easily get stuck on byte order, signature hashing, change, and fees from the start.

Installation Is Not Everything

Installing @bsv/sdk is just the beginning. To actually create transactions, you still need to address the following issues:

Is the wallet available? — The official first transaction tutorial assumes a connectable wallet (e.g., a BRC-100 compliant wallet).
Does the wallet have available funds? — Without spendable UTXOs, you cannot pay output amounts and fees.
Is the app authorized by the wallet? — When using WalletClient, the app usually needs user confirmation or authorization.
Is the network broadcastable? — After creation, the transaction must be accepted by the processing network to get a queryable on-chain result.

These issues belong to the runtime environment, which the SDK package alone cannot fully solve.

Why Not Handwrite Transactions from the Start

Handwriting transactions is indeed important, but it is not suitable as the first step.

A real transaction requires many steps:

Find spendable UTXOs
Construct inputs
Construct outputs
Calculate fees
Generate change output
Generate correct signatures for each input
Serialize transaction
Broadcast transaction
Handle transaction status

The SDK’s high-level interfaces encapsulate these steps first, allowing you to see the complete result. The learning order should be to get it working first, then deconstruct. Stage 7 is 'getting it working,' Stage 8 is 'deconstructing.'

Common Misunderstandings for Beginners

Successful installation ≠ Successful wallet connection — npm install @bsv/sdk only means the project has the dependency.
SDK ≠ Blockchain node — The SDK is an application-side tool, not a miner node or a complete transaction processing network.
Code runs ≠ Transaction on-chain — Creating a transaction, broadcasting it, having it accepted, and having it included in a block are different stages.
Official examples may change with SDK versions — When building real projects, always refer to the current official documentation and the actual installed version.