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, and the `oneSat` capability block: implemented 1Sat BRCs, view scopes, spend label, provenance versions, identity-proof rules. The block is documented on the feature map.
`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.

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.

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

Deadlines

Origin and permission rules

Checklist for a first integration

​Endpoints

​Ownership

​Discovery

​Responses and errors

​Deadlines

​Origin and permission rules

​Checklist for a first integration

​Related

Endpoints

Ownership

Discovery

Responses and errors

Deadlines

Origin and permission rules

Checklist for a first integration

Related