> ## 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` — forwarded, not the integrator path this release |
| Identity discovery | `discoverByIdentityKey`, `discoverByAttributes`, `revealCounterpartyKeyLinkage`, `revealSpecificKeyLinkage` — forwarded, not the integrator path this release |

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 or tokens requested | `listOutputs` on item and token baskets. Index baskets return `404` on this release. |

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. Fall back to summing basket `default` on `404`. |
| `getClaimedCloudHandle` | The wallet's verified handle binding. Fall back to the identity key on `404`. |

Index and overlay packs (`installIndexExpansion`, `syncIndexExpansion`, `removeIndexExpansion`, `listIndexExpansions`, `listIndexExpansionEntries`, `overlayLookup`) return `404 INDEX_EXPANSION_UNAVAILABLE` on this release.

## 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

* [Feature map](/brc-wallet/feature-map) · [feature-map.md](https://docs.handcash.io/brc-wallet/feature-map.md)
* [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


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