Server Wallet

The server wallet runs on Node.js using a private key and @bsv/wallet-toolbox. It's used for automated operations, payment processing, and funding flows where no user interaction is needed.

Creating a Server Wallet

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

const wallet = await ServerWallet.create({
  privateKey: process.env.SERVER_PRIVATE_KEY!,
  network: 'main',
  storageUrl: 'https://storage.babbage.systems'
})

console.log('Identity Key:', wallet.getIdentityKey())

Configuration

Parameter	Type	Default	Description
privateKey	string	required	Hex-encoded private key
network	'main' | 'testnet'	'main'	Network to operate on
storageUrl	string	'https://storage.babbage.systems'	Wallet storage provider URL

What Happens During Creation

1. A PrivateKey and KeyDeriver are created from the hex key

2. A WalletStorageManager, WalletSigner, and Services instance are configured

3. A StorageClient connects to the storage URL and becomes available

4. The ToolboxWallet is instantiated and all module methods are mixed in

5. The composed ServerWallet is returned

Funding Flow

The server wallet uses a request/response pattern to receive funds from a browser wallet:

Step 1: Server Creates a Payment Request

const request = wallet.createPaymentRequest({
  satoshis: 50000,
  memo: 'Server wallet funding'
})
// Returns: { serverIdentityKey, derivationPrefix, derivationSuffix, satoshis, memo }

This generates a random BRC-29 derivation suffix so the server can later prove ownership of the payment.

Step 2: Browser Wallet Funds the Server

// On the client (browser):
const result = await browserWallet.fundServerWallet(
  paymentRequest,
  'server-funding'       // basket for tracking
)

Step 3: Client Sends Transaction to Server

await fetch('/api/server-wallet?action=receive', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tx: Array.from(result.tx),
    senderIdentityKey: browserWallet.getIdentityKey(),
    derivationPrefix: paymentRequest.derivationPrefix,
    derivationSuffix: paymentRequest.derivationSuffix,
    outputIndex: 0
  })
})

Step 4: Server Internalizes the Payment

await wallet.receivePayment({
  tx: txBytesFromClient,
  senderIdentityKey: clientIdentityKey,
  derivationPrefix: request.derivationPrefix,
  derivationSuffix: request.derivationSuffix,
  outputIndex: 0
})

This uses the wallet payment protocol to internalize the output with proper derivation info, so the server wallet can spend it later.

Private Key Persistence

Key persistence is handled automatically by handler factories. If you need lower-level access, use generatePrivateKey() instead of importing @bsv/sdk:

import { generatePrivateKey } from '@bsv/simple/server'
const key = process.env.SERVER_PRIVATE_KEY || generatePrivateKey()

For Next.js API routes, use the handler factory which manages key persistence automatically:

// app/api/server-wallet/route.ts
import { createServerWalletHandler } from '@bsv/simple/server'
const handler = createServerWalletHandler()
export const GET = handler.GET, POST = handler.POST

Key persistence order (automatic):

1. process.env.SERVER_PRIVATE_KEY — Environment variable (production)

2. .server-wallet.json file — Persisted from previous run (development)

3. Auto-generated via generatePrivateKey() — Fresh key (first run)

Important: Add .server-wallet.json to your .gitignore. Never commit private keys.

Shared Methods

The server wallet has all the same methods as the browser wallet:

• pay(), send()

• createToken(), listTokenDetails(), sendToken(), redeemToken()

• inscribeText(), inscribeJSON(), inscribeFileHash(), inscribeImageHash()

• certifyForMessageBox(), sendMessageBoxPayment(), listIncomingPayments(), acceptIncomingPayment()

• acquireCertificateFrom(), listCertificatesFrom(), relinquishCert()

• getDID(), resolveDID(), registerDID()

• acquireCredential(), listCredentials(), createPresentation()

• advertiseSHIP(), advertiseSLAP(), broadcastAction(), withRetry()

Next.js API Route Example

See the Next.js Integration Guide for a complete API route implementation with caching and key persistence.