ServerWallet

ServerWallet is the composed wallet type for server-side (Node.js) applications. It extends WalletCore with server-specific payment receiving methods, plus all module methods mixed in.

Source: src/server.ts

Import:

// In Next.js API routes, always use dynamic import:
const { ServerWallet } = await import('@bsv/simple/server')

// In standalone Node.js scripts:
import { ServerWallet } from '@bsv/simple/server'

Important: In Next.js, use await import() instead of static import at the top of the file. Static imports cause Turbopack bundling issues.

Type Definition

type ServerWallet = _ServerWallet
  & ReturnType<typeof createTokenMethods>
  & ReturnType<typeof createInscriptionMethods>
  & ReturnType<typeof createMessageBoxMethods>
  & ReturnType<typeof createCertificationMethods>
  & ReturnType<typeof createOverlayMethods>
  & ReturnType<typeof createDIDMethods>
  & ReturnType<typeof createCredentialMethods>

ServerWallet.create()

namespace ServerWallet {
  async function create(config: ServerWalletConfig): Promise<ServerWallet>
}

Factory function that creates a fully-composed ServerWallet.

Parameter	Type	Required	Description
config.privateKey	string	Yes	Hex-encoded private key
config.network	Network	No	'main' (default) or 'testnet'
config.storageUrl	string	No	Storage service URL (default: 'https://storage.babbage.systems')

What happens:

1. Creates a PrivateKey and KeyDeriver from the hex key

2. Initializes WalletStorageManager and WalletSigner

3. Connects to the storage service via StorageClient

4. Mixes in all module methods

Example:

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

Server-Specific Methods

createPaymentRequest()

createPaymentRequest(options: { satoshis: number; memo?: string }): PaymentRequest

Generate a BRC-29 payment request that a browser wallet can fulfill.

Parameter	Type	Required	Description
options.satoshis	number	Yes	Amount requested
options.memo	string	No	Human-readable memo

Returns:

{
  serverIdentityKey: string      // Server's public key
  derivationPrefix: string       // Base64-encoded prefix
  derivationSuffix: string       // Base64-encoded random suffix
  satoshis: number               // Requested amount
  memo?: string                  // Optional memo
}

receivePayment()

async receivePayment(payment: IncomingPayment): Promise<void>

Internalize a payment received from a browser wallet using the wallet payment protocol.

Parameter	Type	Required	Description
payment.tx	number[] | Uint8Array	Yes	AtomicBEEF transaction bytes
payment.senderIdentityKey	string	Yes	Sender's identity key
payment.derivationPrefix	string	Yes	BRC-29 derivation prefix
payment.derivationSuffix	string	Yes	BRC-29 derivation suffix
payment.outputIndex	number	Yes	Index of the payment output
payment.description	string	No	Transaction description

Shared Methods

ServerWallet inherits all methods from WalletCore and all module methods (tokens, inscriptions, messagebox, certification, overlay, DID, credentials). See the BrowserWallet page for the full method listing.

Funding Flow

The typical server wallet funding flow:

1. Server: wallet.createPaymentRequest({ satoshis: 50000 })
       ↓ (send PaymentRequest to client via API)
2. Client: wallet.fundServerWallet(request, 'funding')
       ↓ (send tx bytes back to server via API)
3. Server: wallet.receivePayment({ tx, senderIdentityKey, ... })

See the Server Wallet Guide for a complete example.

Key Persistence

In production, set the private key via environment variable:

SERVER_PRIVATE_KEY=a1b2c3d4e5f6...

For development, 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

Or for lower-level access, use generatePrivateKey() (no @bsv/sdk import needed):

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

Add .server-wallet.json to .gitignore.

Dependencies

ServerWallet requires @bsv/wallet-toolbox, which is a Node.js-only dependency. It must be listed in serverExternalPackages in next.config.ts to avoid Turbopack bundling it for the browser:

serverExternalPackages: ["@bsv/wallet-toolbox", "knex", "better-sqlite3", ...]