# Connect to a wallet with WalletClient

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

WalletClient from @bsv/sdk finds the user's BRC-100 wallet and sends it method calls, from a browser or from Node.js.

import BlueTable from '/snippets/BlueTable.jsx';

Connect a Node.js script to [BSV Desktop](https://bsvblockchain.com/docs/wallets/bsv-desktop/) with `WalletClient`, confirm that the wallet answers on testnet, and read its identity key. Use `WalletClient` when your app asks the user's wallet to create transactions, sign data or show keys, so that your code never holds a private key. The same class runs in a browser and in Node.js, and it calls any wallet that implements BRC-100 (The standard set of methods an app calls on a user's wallet). The example runs standalone, with read only calls that spend nothing. This page was written against `@bsv/sdk` 4.0.1 and Node.js 24.

## Before you begin

You need:

- Node.js 22 or newer, and a project with `"type": "module"` in its `package.json` and `@bsv/sdk` installed. See [Install the SDK in Node or React](https://bsvblockchain.com/docs/sdk/typescript/setup/). To install the version this page was written against, run this in the project folder:

  ```bash
  npm install @bsv/sdk@4.0.1
  ```

- BSV Desktop open and set to testnet. To set it up, follow [Set up a testnet wallet](https://bsvblockchain.com/docs/get-started/quick-start-browser/#set-up-a-testnet-wallet) in the Quick Start.

## How it works

`WalletClient` holds no keys, the wallet does (see [BRC-100: Wallet Application Interface](https://bsvblockchain.com/docs/concepts/wallet-model/)). Each method you call, such as `getPublicKey`, travels to the wallet over a substrate, the transport between your code and the wallet, and the wallet answers or asks the user to approve. The constructor takes two values:

```ts
new WalletClient(substrate, originator)
```

- `substrate` picks the transport. The default, `'auto'`, finds the wallet for you.
- `originator` is the name of your app, a hostname with an optional port such as `example.com` or `localhost:8080`. The wallet shows it when it asks the user to approve a request, and stores every permission of your app under it. In a browser, the page origin is sent instead. In Node.js you must pass it, since a script has no origin of its own.

The constructor does not connect. With `'auto'`, the first method call tries these substrates at the same time, waits up to 1 second for each, and keeps the first one that answers, in this order:

<BlueTable>

| Substrate | Where the wallet listens |
| --- | --- |
| `window.CWI` | An object injected into the browser page |
| `Cicada` | `http://localhost:3301`, binary wire format |
| `secure-json-api` | `https://localhost:2121`, JSON |
| `json-api` | `http://localhost:3321`, JSON, where BSV Desktop answers |
| `react-native` | The React Native WebView bridge |

</BlueTable>

If none answers, `WalletClient` tries `XDM`, a `postMessage` bridge to a parent window that holds the wallet, for 200 milliseconds. Every later call reuses the substrate that answered.

## Connect to BSV Desktop

Write a script that calls five read only wallet methods, then run it. Create `connect.mjs` in your project folder:

> The script prints the identity key of your wallet. The key is public, but it links your activity across apps, so do not paste the key of a wallet you use in shared logs or issues.

**1. Write the script**

Create the client with the default substrate and `localhost` as the originator, then read the session, the network, the wallet version, the block height and the identity key:

```js connect.mjs
import { WalletClient } from '@bsv/sdk'

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

const { authenticated } = await wallet.isAuthenticated()
const { network } = await wallet.getNetwork()
const { version } = await wallet.getVersion()
const { height } = await wallet.getHeight()
const { publicKey } = await wallet.getPublicKey({ identityKey: true })

console.log('Authenticated:', authenticated)
console.log('Network:', network)
console.log('Wallet version:', version)
console.log('Block height:', height)
console.log('Identity key:', publicKey)
```

- `isAuthenticated` returns `true` when the user is signed in to the wallet.
- `getNetwork` returns `testnet` or `mainnet`, the network the wallet is set to. Check it before you create transactions, so that your app does not send coins on the wrong network.
- `getPublicKey({ identityKey: true })` returns the public identity key of the wallet, a 66 character hexadecimal string that identifies the user to other apps. It is public and safe to share.

**2. Run the script**

Run it from the project folder, with BSV Desktop open:

```bash
node connect.mjs
```

Your height and identity key differ. The key shown is a placeholder:

```text
Authenticated: true
Network: testnet
Wallet version: wallet-brc100-1.0.0
Block height: 1768236
Identity key: 02aaaaaa…aaaaaaaa
```

`Network: testnet` confirms that the script reached BSV Desktop on the network the examples on this site use. In this run, `'auto'` connected over `json-api`, the HTTP port of BSV Desktop.

## Choose a substrate

To skip the discovery, pass the name of a substrate instead of `'auto'`. The client then connects only over that transport:

```js
const wallet = new WalletClient('json-api', 'localhost')
```

Keep `'auto'` for an app that runs where you do not control which wallet the user has, such as a public web page. Name the substrate in a script or a test that always talks to the same wallet, such as BSV Desktop over `json-api`. You can also pass a substrate object, for example `new WalletClient(new XDM('https://wallet.example'))`, with `XDM` imported from `@bsv/sdk`, to accept messages from that wallet origin only.

## Call BRC-100 methods

`WalletClient` has the 28 methods of BRC-100. Each one takes one object of arguments and returns a promise:

<BlueTable>

| Group | Methods | Use them to |
| --- | --- | --- |
| Actions | `createAction`, `signAction`, `abortAction`, `listActions`, `internalizeAction` | Create transactions, sign them in two steps, list past ones and accept incoming payments |
| Outputs | `listOutputs`, `relinquishOutput` | List the outputs the wallet tracks for your app, by basket, and stop tracking one |
| Keys and cryptography | `getPublicKey`, `revealCounterpartyKeyLinkage`, `revealSpecificKeyLinkage`, `encrypt`, `decrypt`, `createHmac`, `verifyHmac`, `createSignature`, `verifySignature` | Derive keys, encrypt and sign data with keys the app never sees |
| Certificates and identity | `acquireCertificate`, `listCertificates`, `proveCertificate`, `relinquishCertificate`, `discoverByIdentityKey`, `discoverByAttributes` | Hold identity certificates, reveal some of their fields and find other users |
| Session and chain | `isAuthenticated`, `waitForAuthentication`, `getHeight`, `getHeaderForHeight`, `getNetwork`, `getVersion` | Check the wallet state and read block headers |

</BlueTable>

A method that spends coins, such as `createAction`, opens an approval request in the wallet, and the promise waits until the user answers. A payment the user approves is broadcast and cannot be reversed. To send a payment with `createAction`, follow [Send your first payment](https://bsvblockchain.com/docs/get-started/quick-start-browser/#send-your-first-payment) in the Quick Start. For the arguments and results of every method, see the [BRC-100 wallet standard](https://bsvblockchain.com/docs/standards/brc-100/).

## Troubleshooting

**Script fails with "No wallet available over any communication substrate"**

The full message is `No wallet available over any communication substrate. Install a BSV wallet today!`. `WalletClient` with `'auto'` found no wallet on any substrate. Open BSV Desktop and unlock it, then run the script again. In Node.js, the same message appears when the constructor has no originator, even with BSV Desktop open, because every HTTP substrate refuses the call. Pass a name as the second argument, such as `new WalletClient('auto', 'localhost')`.

**Script fails with "originator is required when using the HTTP substrate in Node.js"**

A client with a named HTTP substrate, such as `new WalletClient('json-api')`, was created without an originator in Node.js. Pass the name of your app as the second argument, such as `new WalletClient('json-api', 'localhost')`.

**Constructor fails with "The originator parameter must be a canonical DNS hostname"**

The originator holds more than a hostname and a port, such as `https://my.app` or a path. Pass the hostname alone, with an optional port, such as `my.app` or `localhost:8080`.

## Next steps

With the wallet connected, set up the permissions of your app or let users log in with their wallet:

- [Request permissions and organize outputs](https://bsvblockchain.com/docs/guides/wallet-aware-apps/)
- [Let users log in with any wallet](https://bsvblockchain.com/docs/guides/wallet-login/)
- [BRC-100 wallet standard](https://bsvblockchain.com/docs/standards/brc-100/)