Read these as markdown
Each task page is published as markdown. Hand an agent the.md URL, or open it yourself.
How to read this page
Connect (@handcash/sdk) is a cloud API: your server holds appId and appSecret, the user hands you an authToken, and HandCash executes on their behalf. The BRC wallet is the user’s own keys on Desktop or Mobile: your app is identified by its origin, the user approves each capability once, and every payment, item, and token is a transaction your app describes and the wallet signs.
That is why the right-hand column is short. Payments, items, and tokens are not separate APIs on the BRC wallet — they are createAction, internalizeAction, and listOutputs with different scripts, baskets, and tags.
WalletClient already implements the BRC-100 method names below. There is no HandCash SDK for the BRC wallet, and the same code runs against any conforming wallet.
Ship this
Hand these four to a developer integrating today. Each one has HandCash behavior in front of the wallet call: an origin gate, a prompt, a scope check, or a funds preflight. Desktop answers onhttp://127.0.0.1:3321.
Ordinary signing rides along with auth when a back end needs proof the wallet holds the key:
getPublicKey, createSignature, verifySignature, encrypt, decrypt, createHmac, verifyHmac. A createSignature whose protocolID is [2, 'wallet identity proof'] is checked against the calling origin. Any other protocol is signed as a normal BRC-42 signature.
Two HandCash conveniences are safe behind a 404 check: getBalance (otherwise sum basket default) and getClaimedCloudHandle (otherwise the identity key).
Leave the rest of this page for later. Certificates, identity discovery, and key-linkage reveals are forwarded to the wallet and have no HandCash proof that a third-party call succeeds. BRC-230 returns 404. Market, migration, and handle writes return 403 to every other origin.
Authentication and identity
Task page: Permissions and scopes · permissions.md
Payments
Task page: Payments and actions · payments.md
Items (collectables)
The 1Sat stack
“Items” on the BRC wallet is four BRCs riding onlistOutputs, createAction, and internalizeAction. The bridge advertises which ones it implements in oneSat.brcs, so an app can check before it builds an inscription.
Storage and permission are separate. Held collectables live in
1sat; your app never names that basket on a read. listOutputs({ basket: '1sat' }) returns 400 USE_P1SAT_SCOPE.
View rules. The scope is one of all, collection, app, creator, id. The value is always a tag, never part of the basket name. A non-all scope with no matching tag, a bare p 1sat, an unknown scope, or a value embedded in the basket name fails closed. Extra tags narrow a request but cannot widen it: the wallet post-filters to the granted axis even when you send tagQueryMode: 'any'. app: and creator: are different axes. p 1sat id with one id: tag resolves without a prompt, which makes it the right call for a detail screen.
A view returns tags plus the wallet’s originVerified verdict. Provenance BEEF is not a view payload; the wallet never hands a 700-row inventory its proofs. Fetch one row with include: 'entire transactions' when you need the transaction itself.
Spend rules. Every label p 1sat input id <key> must resolve to exactly one held row, and that row’s outpoint must appear in inputs, or the call fails with 400 INVALID_P1SAT_SPEND before any prompt. Each item spend is approved per action. Pay and auto-pay grants never cover item view or item spend.
What the bridge advertises. GET /health and GET /manifest.json both carry this block. Branch on it, not on the wallet’s name.
provenanceVerify: ['v2'] means the wallet shows an item as verified only on a complete BRC-150 v2 proof. BRC-156 soft-latch was withdrawn and is not advertised.
Task page: Collectables · items.md
Tokens (BSV-21)
Task page: Tokens · tokens.md
Signing and encryption
Task page: Signing and encryption · signing.md
Social, business, and embedded wallets
Errors
Full list with HTTP statuses: Permissions and scopes · permissions.md.
How BRC-100 grows
Connect grew by adding endpoints:pay, then getItemsInventory, then createItemsOrder, each a new SDK function with its own shape. BRC-100 does not grow that way. The method list is fixed and small; new functionality arrives in three layers, and each layer has a different portability guarantee.
Layer 1: the core interface
The wallet dispatches the BRC-100 method set as published, andgetVersion names the interface it speaks. @bsv/sdk WalletClient covers this layer. Ship the groups marked ready. The others are forwarded and unproven in this release.
Layer 2: protocols that ride on the core
This is where features live. A payment, a collectable, and a fungible token are the same three calls with different scripts, baskets, tags, labels, andcustomInstructions. A wallet that adds support for a new protocol adds no methods; it learns to build, index, and verify a new kind of output.
The permission grammar is part of this layer too.
p 1sat collection and p bsv21 id are baskets in the BRC-100 sense — the wallet interprets them as scoped views. Another wallet may use a different grammar, so treat the scope string as a HandCash convention and the underlying listOutputs call as portable.
Layer 3: methods HandCash adds
These travel over the same loopback bridge, use the same JSON envelope, and are not in BRC-100. Feature-detect them and keep a portable fallback.
Methods reserved for HandCash hosts refuse any other origin: market (
createMarketListingAdvert, createMarketPurchaseIntent, purchaseMarketListing, createCancelMarketListingAdvert, getTokenIcon → 403 MARKET_ORIGIN_DENIED), migration (getLegacyAddress, refreshLegacyAddress, listMigrationTxids) and handle administration (claimCloudHandle, clearClaimedCloudHandle) → 403 MIGRATION_ORIGIN_DENIED, and createAdminIdentityProof (HandCash operations only).
The origin is taken from the browser’s Origin header first, then an originator header for non-browser clients. That is the identity every grant is keyed to.
Discovering what a wallet supports
Do this at connect time, once, and branch on the result rather than on the wallet’s brand.
Probe extensions only after
waitForAuthentication has resolved, so a probe can never be the thing that prompts the user.
The rule for app authors
Ship auth, payments, items, and plain BSV-21, plus ordinary signing when a back end must check the key. Pick those protocols from Layer 2. UsegetBalance and getClaimedCloudHandle only behind a 404 check. Leave certificates, identity discovery, key-linkage reveals, and BRC-230 off the integration until this repo shows a third-party call succeeding. That is the point of not shipping a HandCash SDK for the BRC wallet: the calls above are BRC-100, and the rest is not ready to wrap.
Transport
Task page: Local bridge · local-bridge.md. Live examples: Transaction Bounce and the wallet demo.