> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Module 3: Wallets and addresses in Bitcoin Core

> Wallet management from the CLI: creating and loading wallets, generating address types, and labeling addresses for tracking.

## Learning objectives

* Create and load Bitcoin Core wallets via the CLI
* Generate Bech32 and legacy-style addresses
* Understand the difference between active and watch-only wallets
* Use labels to track address purposes or user flows

## Creating and loading wallets

Bitcoin Core supports multiple wallets.

Create a new wallet:

```bash theme={null}
bitcoin-cli -regtest createwallet "user_wallet"
```

This:

* Creates a directory at \~/.bitcoin/regtest/wallets/user\_wallet
* Initializes a keypool and metadata
* Loads the wallet into memory automatically

List currently loaded wallets:

```bash theme={null}
bitcoin-cli -regtest listwallets
```

Load an existing wallet manually:

```bash theme={null}
bitcoin-cli -regtest loadwallet "user_wallet"
```

> [!NOTE]
>
> Wallets must be loaded to interact with them (e.g. send, getbalance, generate addresses).

## Generating new addresses

Once a wallet is loaded, generate a new address:

```bash theme={null}
bitcoin-cli -regtest getnewaddress
```

To specify a label (more on this below):

```bash theme={null}
bitcoin-cli -regtest getnewaddress "payroll"
```

To choose an address format:

```bash theme={null}
bitcoin-cli -regtest getnewaddress "" bech32
bitcoin-cli -regtest getnewaddress "" legacy
```

Caution:

Wallets must be loaded to interact with them (e.g. send, getbalance, generate addresses).

## Address formats: Bech32 vs legacy

| Format | Cli String | Looks Like | Pros |
| - | - | - | - |
| Bech32 | bech32 | bc1... | Lower fees, native SegWit, modern |
| P2SH | p2sh-segwit | 3... | SegWit wrapped in P2SH |
| Legacy | legacy | 1... | High fees, no SegWit support |

In production, always prefer Bech32 unless interacting with legacy systems.

## Watching vs active wallets

Active wallets:

* Contain private keys
* Can sign and spend

Watch-only wallets:

* Only store addresses (public keys)
* Cannot spend, used for audit or monitoring

Add a watch-only address. Bitcoin Core's descriptor wallets need a wallet with private keys disabled:

```bash theme={null}
bitcoin-cli -regtest createwallet "watchonly" true true
DESC=$(bitcoin-cli -regtest getdescriptorinfo "addr(<address>)" | jq -r .descriptor)
bitcoin-cli -regtest -rpcwallet=watchonly importdescriptors "[{\"desc\":\"$DESC\",\"timestamp\":\"now\",\"label\":\"external\"}]"
```

Use listunspent or getbalance to see funds received to that address.

## Using labels for addresses

Labels help you track usage or assign context to addresses.

```bash theme={null}
bitcoin-cli -regtest -rpcwallet=user_wallet getnewaddress "savings"
```

Now you can query:

```bash theme={null}
bitcoin-cli -regtest -rpcwallet=user_wallet getaddressesbylabel "savings"
```

Labels are stored per-wallet. Use them to track:

* Payment types (e.g. salary, invoice)
* Customer IDs
* Internal routing (e.g. swap\_funding)

## Activity

Run the following:

1. Create a wallet: demo\_wallet
2. Load it if needed: loadwallet demo\_wallet
3. Generate one Bech32 and one legacy address.
4. Add a watch-only address for a friend’s wallet (replace \<friends\_address> with an actual address).
5. Label two addresses: one for merchant, one for salary.

Bonus:

```bash theme={null}
bitcoin-cli -regtest -rpcwallet=demo_wallet getwalletinfo
bitcoin-cli -regtest -rpcwallet=demo_wallet listreceivedbylabel
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.