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

# Local bridge

> Connect a web or local app to the HandCash BRC wallet Desktop bridge (beta)

<Warning>
  **Beta — HandCash BRC wallet (Desktop).** Bridge ports, TLS, and origin allowlists can change. This page is for the **local BRC-100 bridge**, not cloud Connect or Wallet API.
</Warning>

## Endpoints

When HandCash Desktop is running and unlocked, apps reach the wallet on loopback:

| Role     | URL                      |
| -------- | ------------------------ |
| Primary  | `https://127.0.0.1:2121` |
| Fallback | `http://127.0.0.1:3321`  |

Use the primary HTTPS endpoint when available; fall back to `3321` if the primary is unreachable (some environments reject the local certificate).

## Ownership

* **Desktop** owns the local BRC-100 bridge and the permission UX.
* Your app must present a clear **origin** the wallet can approve or deny.
* Method payloads should match [BRC-100](https://brc.dev/100). HandCash-specific migrate / claim helpers may be origin-gated to HandCash hosts.

## Discovery

Use `POST /getVersion` with `{}` as the body. This is the BRC-100 substrate
probe used by wallet clients:

```typescript theme={null}
const response = await fetch('https://127.0.0.1:2121/getVersion', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    originator: location.host,
  },
  body: '{}',
})
```

Also available:

| Endpoint             | Purpose                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `GET /health`        | Lightweight listener health and advertised HandCash capabilities.                          |
| `GET /manifest.json` | Wallet identity, trust metadata, `1sat`, identity-proof, and index-extension capabilities. |
| `POST /{method}`     | One JSON BRC-100 method call.                                                              |

`GET /health` does not prove that the renderer is unlocked and ready to answer
wallet calls. Use `getVersion` for wallet discovery.

## Responses and errors

Successful methods return their BRC-100 JSON result with HTTP `200`. Errors
are JSON:

```json theme={null}
{
  "status": "error",
  "code": "WALLET_LOCKED",
  "description": "Unlock HandCash to use the BRC-100 interface."
}
```

Common bridge errors:

| HTTP  | Code                                   | Meaning                                                    |
| ----- | -------------------------------------- | ---------------------------------------------------------- |
| `401` | `NOT_AUTHENTICATED`                    | Connect this origin with `waitForAuthentication`.          |
| `403` | `PERMISSION_DENIED` / `ACTION_DENIED`  | The user denied connection or the specific action.         |
| `400` | `INSUFFICIENT_FUNDS`                   | Spendable local wallet state cannot fund the action.       |
| `400` | `USE_P1SAT_SCOPE` / `USE_PBSV21_SCOPE` | Use a permission basket, not an internal inventory basket. |
| `503` | `WALLET_LOCKED`                        | Desktop is running but the wallet is locked.               |
| `503` | `OFFLINE_PAYMENTS_DISABLED`            | A mutating payment was refused while offline.              |

Do not retry a mutating request blindly after a transport timeout: the wallet
may have completed it after the caller disconnected. Reconcile by label,
transaction ID, or application protocol state first.

## Deadlines

The bridge holds your request while the user decides: roughly **120 seconds**
for reads and prompts, **300 seconds** for spends. Past that you get
`503 WALLET_BRIDGE_TIMEOUT` for a read or `503 WALLET_BRIDGE_PENDING` for a
spend, and `WALLET_BRIDGE_PENDING` may still complete afterwards. If your HTTP
client disconnects, the wallet cancels the pending prompt.

Other transport failures are `503 WALLET_BRIDGE_UNAVAILABLE` when the wallet
window cannot answer and `500 HTTP_BRIDGE_ERROR` for anything else.

## Origin and permission rules

Your origin identifies your app, and the wallet gates methods in tiers: public
discovery, a one-time connection, per-action approval, and separate scoped
grants for item, token, and catalog reads. Market, migration, handle-claim, and
administrative helpers are restricted to HandCash-owned hosts.

Full rules, grant behaviour, and every permission error code:
**[Permissions and scopes](/brc-wallet/permissions)**.

## Checklist for a first integration

1. User installs and unlocks **HandCash Desktop**.
2. Your app probes `getVersion` on `2121`, then `3321`.
3. It calls `isAuthenticated`, then `waitForAuthentication` if needed.
4. The user grants your origin and any action-specific permissions.
5. Your app calls standard BRC-100 methods and handles structured errors.
6. It never treats cloud Connect `authToken` or WaaS access keys as substitutes for this path.

## Related

* **[Getting started](/brc-wallet/getting-started)**
* **[Wallet interactions](/brc-wallet/interactions)**
* **[Payments and actions](/brc-wallet/payments)**
* **[Permissions and scopes](/brc-wallet/permissions)**
* **[Overview](/brc-wallet/overview)**
* Protocol: [BRC-100](https://brc.dev/100)
* Live board: [App Lab](https://brc-cloud.bcryderman.workers.dev/app-lab)