Get Started

Most application developers should start above the BRC-100 boundary. Your app asks a wallet to do something; the wallet keeps keys, output selection, signing, and storage under its control.

Step 1: Install

npm install @bsv/simple

Use @bsv/sdk directly only when you need protocol-level control over keys, scripts, transactions, BEEF, BUMP, or the raw BRC-100 WalletClient.

If you are coming from another blockchain stack and want to build transactions explicitly, start with @bsv/wallet-helper. It is more technical than @bsv/simple, but easier to work with than direct WalletClient.createAction and signAction calls.

Step 2: Connect to a User Wallet

Browser apps use @bsv/simple/browser. Under the hood it creates a BRC-100 wallet client and discovers an available wallet substrate such as BSV Desktop over localhost or BSV Browser over a postMessage bridge.

import { createWallet } from '@bsv/simple/browser'

const wallet = await createWallet()

console.log(wallet.getIdentityKey())
console.log(wallet.getAddress())

Private keys stay in the user's wallet application. The web app receives method results such as transaction IDs, AtomicBEEF bytes, public keys, signatures, or listed outputs depending on the method called.

Step 3: Do Something Useful

Send a peer-to-peer payment to an identity key:

const recipientIdentityKey = '025706528f0f6894b2ba505007267ccff1133e004452a1f6b72ac716f246216366'
const result = await wallet.pay({
  to: recipientIdentityKey,
  satoshis: 1000
})

console.log(result.txid)

Create and inspect an encrypted PushDrop token in a basket:

const created = await wallet.createToken({
  data: { type: 'reward', points: 100 },
  basket: 'rewards'
})

const tokens = await wallet.listTokenDetails('rewards')
console.log(created.txid, tokens[0]?.outpoint)

Get the raw BRC-100 wallet client when you need the method-level interface:

const client = wallet.getClient()

const { outputs } = await client.listOutputs({
  basket: 'rewards',
  include: 'locking scripts',
  includeCustomInstructions: true
})

console.log(outputs.length)

Server Agents

Server-side agents use @bsv/simple/server. They manage their own key and can connect to Wallet Infra for storage.

import { ServerWallet } from '@bsv/simple/server'

const wallet = await ServerWallet.create({
  privateKey: process.env.SERVER_PRIVATE_KEY!,
  network: 'main',
  storageUrl: 'https://store-us-1.bsvb.tech'
})

console.log(wallet.getIdentityKey())

Do not generate and discard a production private key at runtime. Persist it in your secret manager and pass it as SERVER_PRIVATE_KEY.

What to Read Next