WalletClient: Communication Entry Point for BSV Wallets

In a Nutshell

WalletClient is the communication entry point between an application and a wallet: the application says "I want to create this transaction," and the wallet handles authorization, signing, UTXO management, and some transaction processing details.

This is crucial because real BSV applications should generally not directly use the user's private key to sign. The application should describe the transaction intent and let the wallet perform sensitive operations after user authorization.

WalletClient Is Not the Wallet Itself

A common misconception for beginners: the name "WalletClient" includes "Wallet," but it is not a keystore or a wallet balance database. More precisely, it is a client. It connects to a wallet implementation through a communication method. The official SDK documentation calls this communication method a substrate, which can take various forms: autoselect, local JSON API, browser environment, cross-window communication, React Native, etc.

Simplified understanding:

Code

1Your application code

2 -> WalletClient

3 -> Wallet interface

4 -> User authorization

5 -> Wallet creates, signs, broadcasts or returns transaction result

The application does not need to know where the private key is, nor should it ask users to input their mnemonic phrase into the application. The wallet is responsible for safeguarding keys and, when necessary, asking users to confirm operations.

Relationship with BRC-100

BRC-100 is the BSV wallet-to-application interface standard. Its goal is to enable applications to communicate with different wallets in a consistent way, rather than each wallet designing a proprietary API.

The official TypeScript SDK implements BRC-100 interfaces in WalletClient. This means applications can request actions from wallets through standardized methods, such as:

Create transactions.
Sign transactions.
Manage spendable outputs.
Query wallet information.
Handle identity and authorization related operations.

For beginners, the key takeaway is: WalletClient allows applications to avoid directly managing private keys and writing custom integration logic for each wallet.

Minimal Connection Example

The first transaction tutorial in the official SDK uses something like the following to connect to a wallet:

TYPESCRIPT

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

3const wallet = new WalletClient('auto', 'localhost')

Here, 'auto' tells the SDK to automatically select the appropriate wallet communication method. 'localhost' is a common originator identifier for local development. The specific parameters may vary depending on the wallet environment and SDK version; for production projects, refer to the current wallet and SDK documentation.

After connection, the application typically calls a wallet method, for example:

TYPESCRIPT

1const response = await wallet.createAction({

2 description: 'My first BSV transaction',

3 outputs: []

4})

A real transaction cannot always have empty outputs; this is just to illustrate the calling relationship. Subsequent articles will explain the parameters of createAction() in detail.

What Complexities Does WalletClient Isolate?

Private key isolation: The application does not touch private keys directly, reducing the risk of key leakage.
UTXO management isolation: The wallet knows which spendable outputs the user has; the application does not need to maintain a complete UTXO set.
Signing process isolation: The application can describe which outputs to spend and which new outputs to create; the wallet generates the corresponding signatures.
User authorization isolation: The wallet can show the transaction description to the user and let them decide whether to approve.
Wallet implementation isolation: As long as wallets follow the same interface, the integration cost for applications is reduced.

Position in the BSV Technology Stack

BSV application development is not just about "putting together a transaction." Real applications also involve identity, authorization, payments, data publication, state updates, token outputs, querying, and indexing. The wallet interface is one of the entry points for these operations.

On the user side, the wallet is the control point for funds and identity.
On the application side, WalletClient is the code entry point for requesting these capabilities.
On the network side, transactions must still comply with BSV protocol rules and be accepted by the transaction processing network.

Thus, it is not a "shortcut around the protocol" but rather "an interface to use the protocol at the application layer."

Difference from Direct Private Key Usage

Code that uses private keys directly typically looks like:

Application reads private key
Application selects UTXOs
Application constructs transaction
Application signs
Application broadcasts

This approach is suitable for certain backend services, test scripts, or low-level learning, but not for general user applications.

The WalletClient approach is:

Application describes the action
Wallet checks and authorizes
Wallet manages UTXOs
Wallet signs
Wallet returns the result

This is more aligned with the security boundaries of user applications.

Common Beginner Misconceptions

WalletClient is not a private key object. It is a communication client.
Connecting to a wallet does not mean the user has authorized all operations. Specific transactions still require authorization or policy checks.
The wallet automatically handles UTXOs, but that does not mean the application can ignore output scripts. The application still needs to know whether it is creating a payment output, data output, or application protocol output.
Different wallets may have different available capabilities. BRC-100 provides a standard interface, but the actual deployment environment, permissions, and user experience may vary.
Success in local development does not guarantee direct deployment to production. Production environments must handle permissions, errors, retries, user prompts, and transaction status.

WalletClient: The Communication Entry Point Between Applications and Wallets