Local bridge

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.

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

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:

{
  "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.

Origin and permission rules

Public chain/discovery calls do not connect an app.
isAuthenticated is silent.
waitForAuthentication opens the origin connection prompt.
Transaction, signature, disclosure, and destructive methods may open a second action-specific prompt.
Item, token, and index reads have separate scopes; a general connection does not expose all wallet inventory.
Market, migration, handle-claim, and administrative helpers are restricted to HandCash-owned hosts.

Checklist for a first integration

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

Get Started

BRC wallet (Beta)

v3 / Getting Started

v3 / Connect

v3 / Payments

v3 / Items

v3 / Business Wallet

v2 / Item Operations

v2 / Collection Management

v2 / Friends

API / Payment Requests

Wallet API / Whitelabel Services

Endpoints

Ownership

Discovery

Responses and errors

Origin and permission rules

Checklist for a first integration

​Endpoints

​Ownership

​Discovery

​Responses and errors

​Origin and permission rules

​Checklist for a first integration

​Related

Endpoints

Ownership

Discovery

Responses and errors

Origin and permission rules

Checklist for a first integration

Related