Custody as a product decision

Who holds the keys in your product: the user's own wallet, the product holding funds, or an arrangement in between, compared as onboarding, support, recovery and responsibility trade-offs.

Whoever holds the keys can move the money, and nobody can reverse the payment. So who holds them decides your onboarding, your support load, what happens when a user loses a phone, and what happens to your users if your company stops. Decide it on purpose, early, and tell users plainly.

Holding other people's money also has legal consequences that differ by jurisdiction and need advice there. This page treats custody as product risk only.

Three arrangements

The user holds the keys, the app connects

The user has their own wallet. Your app asks it to make payments, sign or prove something, and the wallet decides whether to allow it. Your app never sees a key. This is how the guide recommends apps work. See Connecting a wallet.

For the user: their money stays theirs if you disappear, and they can revoke your app in one tap. They also need a wallet before they can use you, and they are responsible for its backup.

For the team: no funds to secure, and no recovery to run. You depend on the user having, or getting, a connected wallet, and your support cannot fix a problem inside it.

The product holds the funds

Your service holds the keys, or holds funds on the user's behalf. This includes a prepaid balance kept inside your app, which the guide calls "a custody problem you created" in Charging per use.

For the user: the familiar model. A password reset works, and there is someone to call. Their money is only as safe as your company, and only reachable while it exists.

For the team: the easiest onboarding and the heaviest responsibility. Every key you hold is a target, every account recovery is a chance to hand money to the wrong person, and your users' funds depend on your security and your survival.

Arrangements in between

The guide describes several, each giving the service part of the control, not all of it. See Private key management.

A share held by a service. The user's key is split, and your service holds one share or an encrypted backup it cannot read. Your service alone cannot move the money. See Automatic cloud backup.
Co-signing and shared control. A set number of keys must sign, held by the user, other people or a service. The rule is enforced by the network, not your database. See Multi-key and Shared wallet.
Delegated spending. An agent or a feature gets its own wallet with a fixed budget, and the agent cannot reach the user's main funds. See Wallet setups.

For the user: help with recovery without handing over the money. More parts to understand, and a recovery path that can fail if any part was only on the lost device.

For the team: you run a service users depend on for recovery, without holding funds you could lose. You inherit the job of making that service survive, and of testing that recovery works.

Comparing them

	User's own wallet	Product holds funds	In between
Onboarding	Needs a wallet first	Easiest	A setup step, often deferrable
Support	Mostly about connecting	Account recovery and disputes	Recovery help
Lost phone	The user's backup	Your reset process	Your share plus theirs
If you shut down	Their money is unaffected	Users depend on your wind-down	Users need a way out without you
What you can lose	Nothing of theirs	All of it	Availability of recovery

Recommendation

Start from the user's own wallet and move along the scale only for a reason you can name, such as a user group that will not keep a backup. Each step towards holding funds buys easier onboarding with a responsibility you cannot hand back.

Rules for any arrangement

These apply whichever arrangement you choose. Your exposure statement, mentioned below, is the short public list of what your app asks for and keeps.

Write down which arrangement your product uses, in one sentence a user could understand, and put that sentence in the product before the user holds money with you.

Don't

Call an arrangement self-custody if your service can move the user's money or decrypt their key. Say what it is.

Make sure users can move their funds out without your service, and say how in your exposure statement. See Disclose what you use.

Plan what happens to users' money if your company stops, before launch. The plan is part of the product, and users of a service holding a share need it as much as users of a custodial one.

Run a recovery drill on a wiped device before launch, whichever arrangement you choose, and repeat it after any change to backup or key handling.

Train support on the one thing they cannot do. If you do not hold the keys, support must never imply it can recover funds, because that sentence is what impersonators say next.

Don't

Keep a balance on users' behalf just to make many small payments smoother. An allowance in the user's own wallet does that job without the custody.

Holding money for users

Holding a balance on the user's behalf

OK: no balance at all. Payments go from the user's wallet to yours as they happen.
Grey area: a small prepaid balance, shown as the user's money, that they can withdraw to their own wallet at any time, kept for a reason you can name, not to smooth small payments.
Not OK: a balance the user cannot withdraw, or one described as their wallet when it is your account.

Open questions

Do users understand a key share held by a service as different from the service holding their money? No published research tests this for BSV products.
What is the clearest one-sentence description of each arrangement for somebody who has never heard the word custody?
How should a product move a user from a held balance to their own wallet without losing them in the step?

Private key management
Backups: what a complete backup contains
Wallet setups
Business models

Written from: /guide/patterns/connecting-a-wallet/, /guide/how-it-works/private-key-management/overview/, /guide/how-it-works/private-key-management/cloud-backup/, /guide/how-it-works/private-key-management/multi-key/, /guide/how-it-works/wallet-setups/, /guide/how-it-works/backups/, /guide/wallet-patterns/shared-wallet/, /guide/patterns/charging-per-use/.

Checklist

The rules on this page, in a form you can work through.

8 rules

DoWrite down which arrangement your product uses, in one sentence a user could understand, and put that sentence in the product before the user holds money with you.
Don'tCosts trustCall an arrangement self-custody if your service can move the user's money or decrypt their key. Say what it is.
DoCosts moneyMake sure users can move their funds out without your service, and say how in your exposure statement. See Disclose what you use.
DoCosts moneyPlan what happens to users' money if your company stops, before launch. The plan is part of the product, and users of a service holding a share need it as much as users of a custodial one.
DoCosts moneyRun a recovery drill on a wiped device before launch, whichever arrangement you choose, and repeat it after any change to backup or key handling.
DoCosts moneyTrain support on the one thing they cannot do. If you do not hold the keys, support must never imply it can recover funds, because that sentence is what impersonators say next.
Don'tCosts trustKeep a balance on users' behalf just to make many small payments smoother. An allowance in the user's own wallet does that job without the custody.
DoStart from the user's own wallet and move along the scale only for a reason you can name, such as a user group that will not keep a backup. Each step towards holding funds buys easier onboarding with a responsibility you cannot hand back.

Every rule for what you are building