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

# Wallets and balances

## Create a wallet

Use `POST /v1/wallets?environment=sandbox`.

```json theme={null}
{
  "name": "Company Operating wallet"
}
```

The response returns the wallet, including identifiers when available.

## List wallets

Use `GET /v1/wallets?environment=sandbox` to retrieve workspace wallets and derived accounts.

## Derive wallet accounts

Use `POST /v1/wallets/{walletId}/accounts?environment=sandbox`.

```json theme={null}
{
  "network_code": "ethereum_sepolia",
  "count": 1
}
```

`count` must be between `1` and `20`.

## Read balances

Use `GET /v1/balances?environment=sandbox`.

Optional filters:

| Query parameter | Purpose                        |
| --------------- | ------------------------------ |
| `wallet_id`     | Limit balances to one wallet.  |
| `network_code`  | Limit balances to one network. |

Provider failures are surfaced as unknown or stale balance state. Do not treat missing provider reads as zero balance.

## Archive a wallet

Use `POST /v1/wallets/{walletId}/archive?environment=sandbox` to archive a master wallet.

## Address book

Use the address book to manage trusted, untrusted, or blocked destination addresses.

| Endpoint                            | Purpose                    |
| ----------------------------------- | -------------------------- |
| `GET /v1/address-book`              | List address book entries. |
| `POST /v1/address-book`             | Create an entry.           |
| `PUT /v1/address-book/{entryId}`    | Update an entry.           |
| `DELETE /v1/address-book/{entryId}` | Archive an entry.          |

Create or update entries with:

```json theme={null}
{
  "label": "Vendor settlement",
  "address": "0xabc...",
  "network_code": "ethereum_sepolia",
  "asset_symbol": "USDC",
  "trust_status": "trusted",
  "notes": "Approved vendor wallet"
}
```