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

# Wallet interactions

> Everything an app can ask the HandCash BRC wallet to do, and where each task is documented

<Warning>
  **Beta — BRC wallet only.** These methods apply to **HandCash Desktop / Mobile** over [BRC-100](https://brc.dev/100). They are not Connect (`authToken` + `@handcash/sdk`) or Wallet API (`/v1/waas/*`).
</Warning>

Apps talk to the wallet with standard BRC-100 methods. Payments, items, and tokens are not separate APIs — they are transactions your app describes and the user approves.

<CardGroup cols={2}>
  <Card title="Payments and actions" icon="paper-plane" href="/brc-wallet/payments">
    Connect, read balance, send BSV, stage and sign, receive, list history
  </Card>

  <Card title="Collectables" icon="image" href="/brc-wallet/items">
    Read inventory, mint, transfer, and receive 1Sat items
  </Card>

  <Card title="Tokens" icon="coins" href="/brc-wallet/tokens">
    Read balances, mint BSV-21, transfer, and receive tokens
  </Card>

  <Card title="Signing and encryption" icon="key" href="/brc-wallet/signing">
    Identity key, derived keys, signatures, encryption, HMAC, certificates
  </Card>

  <Card title="Permissions and scopes" icon="lock" href="/brc-wallet/permissions">
    Origins, prompts, auto-pay, scoped baskets, error codes, deadlines
  </Card>

  <Card title="Local bridge" icon="plug" href="/brc-wallet/local-bridge">
    Loopback ports, discovery, transport errors
  </Card>
</CardGroup>

## Overview

| Capability         | Methods                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| Discovery          | `getVersion`, `getNetwork`, `getHeight`, `getHeaderForHeight`                                               |
| Connection         | `isAuthenticated`, `waitForAuthentication`                                                                  |
| Keys               | `getPublicKey`                                                                                              |
| Transactions       | `createAction`, `signAction`, `abortAction`, `internalizeAction`, `listActions`                             |
| Items and tokens   | `listOutputs`, `relinquishOutput` — see [Collectables](/brc-wallet/items) and [Tokens](/brc-wallet/tokens)  |
| Cryptography       | `encrypt`, `decrypt`, `createHmac`, `verifyHmac`, `createSignature`, `verifySignature`                      |
| Certificates       | `acquireCertificate`, `listCertificates`, `proveCertificate`, `relinquishCertificate`                       |
| Identity discovery | `discoverByIdentityKey`, `discoverByAttributes`, `revealCounterpartyKeyLinkage`, `revealSpecificKeyLinkage` |

Payload shapes follow [BRC-100](https://brc.dev/100).

## Permissions at a glance

| Level       | What the user sees                                                  | Methods                                                                                                                                             |
| ----------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public      | Nothing                                                             | `getVersion`, `getNetwork`, `getHeight`, `getHeaderForHeight`, `isAuthenticated`                                                                    |
| Connect     | One prompt per app origin                                           | `waitForAuthentication`                                                                                                                             |
| Approval    | A prompt describing the exact transaction, signature, or disclosure | `createAction`, `signAction`, `internalizeAction`, `relinquishOutput`, `createSignature`, `encrypt`, `decrypt`, certificate and key-linkage methods |
| Scoped view | A prompt naming the items, tokens, or catalog requested             | `listOutputs` on item, token, and index baskets, plus the index-expansion methods                                                                   |

Grants are bound to your origin and stored per wallet account. Plain BSV payments can skip the prompt when the user enabled auto-pay; item and token mints, sends, and releases always prompt.

Full model — origin identity, auto-pay and spending limits, scoped basket grammar, every error code, and request deadlines: **[Permissions and scopes](/brc-wallet/permissions)**.

## HandCash extensions

These travel over the same bridge but are not part of BRC-100, so feature-detect them:

| Method                                                                | Purpose                                        |
| --------------------------------------------------------------------- | ---------------------------------------------- |
| `getBalance`                                                          | Spendable BSV in satoshis                      |
| `getClaimedCloudHandle`                                               | The wallet's verified handle binding           |
| `installIndexExpansion`, `syncIndexExpansion`, `removeIndexExpansion` | Manage catalog index packs                     |
| `listIndexExpansions`, `listIndexExpansionEntries`                    | Read installed packs and cached entries        |
| `overlayLookup`                                                       | Query a live overlay through an installed pack |

## Reserved for HandCash hosts

Market, migration, and account-administration methods are origin-gated and return `403` to other apps: `createMarketListingAdvert`, `createMarketPurchaseIntent`, `verifyMarketListingProvenance`, `purchaseMarketListing`, `getMarketSettlementReceipt`, `createCancelMarketListingAdvert`, `getMarketListingStatus`, `markMarketListingPublishFailed`, `getTokenIcon`, `getLegacyAddress`, `refreshLegacyAddress`, `listMigrationTxids`, `claimCloudHandle`, `clearClaimedCloudHandle`, and `createAdminIdentityProof`.

Build on `createAction` and `internalizeAction` instead — they are portable across BRC-100 wallets.

## Next steps

* [Payments and actions](/brc-wallet/payments)
* [Collectables](/brc-wallet/items)
* [Tokens](/brc-wallet/tokens)
* [Signing and encryption](/brc-wallet/signing)
* [Permissions and scopes](/brc-wallet/permissions) — prompts, grants, and error codes
* [Local bridge](/brc-wallet/local-bridge) — transport and discovery