Clone the Formance Ledger repository on GitHub
Run it locally, and post the withdrawal example above against a sandbox instance.
In a self-custody wallet, the client holds the private keys. That single fact changes how your payment platform designs withdrawals, records balances, and meets its compliance obligations.
The product requirement sounds simple: clients can withdraw to their own wallets. In practice, your payment platform must answer two questions for every withdrawal. Who signs the transaction? And how does the ledger represent a destination you can watch but never move? If a custodian holds the keys, you inherit their controls. If the client holds them, your books end at an on-chain address, and your reconciliation model, key management surface, and regulatory posture all change with it.
Whichever custody model you land on, the obligation to keep an accurate system of record stays with you.
This guide walks through what a self-custody wallet is, how the underlying key lifecycle works, how the main signing architectures compare, the trade-offs that platforms inherit, what regulators require in 2025–2026, and how to represent the whole thing in a ledger without losing an audit trail.
A self-custody wallet is a wallet in which the client controls the private keys that authorize transactions, meaning no third party can move the assets. Who can sign determines whether a wallet is self-custodial.
Signing authority defines the payment platform's role. A custodian holds signing authority over client assets and can move them, with the full weight of custody and custodian rules that follow from that signing authority.
A technology provider may ship wallet software and application programming interfaces (APIs). It may also provide signing infrastructure, but it holds no unilateral signing authority and cannot move client assets.
With client self-custody, your payment platform may render balances and construct transactions. It may also broadcast them, but the client signs using keys your payment platform never holds.
Each role carries its own operational and risk profile. Signing capability decides which role you occupy, regardless of what your terms of service say.
Self-custody wallets operate through four lifecycle stages: seed generation and mnemonic encoding, deterministic key derivation, hardened versus non-hardened derivation, and backup via threshold-share splitting.
Everything below sits in the key management layer, the part of the wallet that produces, organizes, protects, and backs up the key material every signature depends on. Each stage becomes an engineering decision when your platform operates the wallet infrastructure.
Many seed-based wallets generate recovery material from randomness and present it as a mnemonic phrase that a person can write down for backup. Compatible wallet software can use that recovery material to recreate the seed from which keys are generated.
The mnemonic is a human-readable encoding of recovery material and must be protected with the same care as signing credentials.
In these wallet designs, every key that signs for the wallet's digital assets ultimately depends on that recovery process.
Many seed-based wallets organize keys deterministically, so that a single backup can restore addresses created under the same derivation scheme. Derivation paths guide compatible software to accounts within that organization.
Cross-software recovery may therefore depend on implementations that follow compatible conventions and search for keys in the same positions.
Hardened derivation keeps child keys behind private material, while non-hardened derivation allows child public keys to be generated from a parent public key alone, which affects what a watch-only deployment can produce from public information.
A payment platform may use non-hardened branches to support address monitoring from public key material without providing signing keys, while reserving hardened branches for derivation that remains behind private material.
Teams must choose which branches monitoring systems can observe without gaining signing authority.
Threshold share splitting replaces a single seed backup with a distributed recovery process. Under a k-of-n policy, recovery is distributed across shares, and a threshold of k must be available to recover the master secret.
Share splitting removes dependence on one backup that can fail as a unit. For an institution, backup combines secure storage with a distribution policy: shares can be spread across officers and sites in different jurisdictions.
A signed transaction is what moves funds on-chain. The wallet constructs an unsigned transaction (sender, recipient, amount, fee, nonce or equivalent), applies the private key to produce a cryptographic signature over that payload, and broadcasts the signed transaction to a node on the target chain.
The node propagates it to the network, with validators or miners including it in a block, and the transaction reaches finality only after the chain's confirmation threshold is met. The wallet itself never holds funds; it holds the keys that authorize the chain to move them.
Everything a self-custody platform observes downstream, from pending state to reconciliation, hangs on this signing-and-broadcast step and the finality guarantees of the chain underneath it.
Payment platforms generally choose among three signing architectures: MPC threshold signing, on-chain multisig, and HSM-backed signing. Each buys a different property at a different operational cost, and all are considered a vital security measure.
Under multi-party threshold schemes, signing authority is distributed among participants, and the configured threshold must be met for a transaction to be authorized. Evaluate whether a particular implementation supports refreshing shares or rotating signers without changing the on-chain address.
MPC threshold signing adds protocol complexity and implementation risk: widely deployed threshold ECDSA protocols have been found to carry a range-proof vulnerability that enables practical key extraction.
MPC wallet architecture for platforms usually arrives through a provider; in-house protocol implementations are less common. An MPC custody connector can feed custody accounts and balances into a core ledger.
Multisig encodes governance in the chain itself, across chains and in implementations that support it. The m-of-n signing structure may be visible on-chain, and execution follows the configured rule.
On-chain transparency can suit shared treasuries and operations where signers must be publicly accountable.
The operational costs depend on the chain and implementation. Changing signers may require a new wallet address and a migration, and each signing key still needs secure storage.
HSM-backed signing protects keys inside a hardware boundary and limits plaintext key export. Modules validated under the Federal Information Processing Standards (FIPS), such as those meeting FIPS 140-3 standards, give you an externally tested cryptographic-module claim independent of the vendor's assertion.
HSM-backed signing suits a single institution operating within its own security perimeter and provides strong protection against key theft. Used on its own, an HSM leaves signing authority concentrated in the organization that operates the module and its access policy.
On February 21, 2025, a multisig cold wallet at Bybit lost roughly $1.5 billion. An incident analysis found that the attack targeted the signing interface rather than the underlying smart contract.
For teams, the security review cannot stop at "we chose MPC" or "we deployed multisig". The interfaces that build, display, and approve signing payloads need the same threat modeling, code review, and monitoring as the key material itself, because that is where funds are actually lost.
The signing workflow is the real security boundary, and depends on how signing requests are constructed, reviewed, and approved.
Self-custody leaves key-recovery, security, data handling and compliance responsibilities in place while shifting ownership of them.
Lost key material can mean lost funds because traditional seed-based self-custody may provide no third-party recovery path or institution with a duty to restore access. Familiar recovery paths include a reset flow and support escalation.
Your team becomes responsible for rehearsed key-ceremony and share-refresh runbooks, including disaster recovery.
Holding your own keys relocates the attack surface, and the relative safety of either custody model depends on how that attack surface is secured.
Personal wallet compromise grew from 7.3% to 44% of the total share of stolen value between 2022 and 2024, while services stayed a target in their own right.
Data-handling responsibility survives the self-custody label, so audit every path in your stack where key material could be logged, cached, or transmitted.
A wallet can market itself as self-custody and still leak funds the moment its client, backend, or telemetry code touches a seed phrase or private key in plaintext, whether through a logging library, an analytics pipeline, an error-reporting service, or an unencrypted API call.
Once your infrastructure has seen the key material, the platform owns the failure regardless of what the product page says.
Compliance visibility remains with your payment platform because legal and compliance teams still need to determine which transaction monitoring and reporting obligations apply to the institution that processes the flow.
Regulatory obligations are the most consequential of those implications, and 2025–2026 rulemakings have reshaped what regulated platforms must assess.
Regulated platforms must assess custody authorization, transaction monitoring, transfer reporting, and capital requirements under each applicable jurisdiction.
Four rulemakings summarized below change the build calculus for any platform weighing self-custody wallet compliance.
Interpretive Letter 1183, issued March 7, 2025, permitted crypto-asset custody by national banks and federal savings associations without prior supervisory nonobjection. Anchorage Digital Bank has operated as a federally chartered digital asset custodian under a conditional OCC national trust charter since January 2021. Regulated crypto custody at the national-bank level is already an operational model.
On December 17, 2025, the Securities and Exchange Commission (SEC) Division of Trading and Markets issued a broker-dealer custody statement. The statement explains its views on how broker-dealers can establish and maintain physical possession of crypto asset securities under the Customer Protection Rule (Rule 15c3-3).
The Basel Framework's SCO60 prudential treatment of cryptoassets was agreed to be implemented by January 1, 2026. The framework gives banks a capital treatment to plan against.
In the European Union (EU), crypto-asset service provider (CASP) custody services sit within the CASP authorization framework. Teams must also assess how evolving cross-border reporting rules treat transfers involving self-custodied addresses in each jurisdiction.
Custody model choice is therefore a compliance-architecture decision. A clearer path for banks and broker-dealers strengthens the case for regulated custody arrangements. Transfer-review, monitoring, and reporting duties must be assessed separately and may remain with your institution even when all wallets involved are self-custodied.
Design the architecture assuming applicable obligations stay with you, because those obligations dictate how your ledger must represent every custody state a regulator can ask about.
Self-custody turns each client wallet into a ledger boundary. Your core ledger holds the obligation and state transition, and the chain holds on-chain settlement.
Client balances live in an omnibus account structure (one on-chain wallet backing many internal accounts), so a withdrawal to a self-custodied address is a boundary event: value leaves an account you model and lands at an address you can only observe.
That boundary event must be a double-entry posting so that wallet debits the client's available balance, credits a pending-withdrawals account for the same asset and amount, and holds the pending state until the chain's finality threshold is met.
Here is the initial posting in Numscript, Formance's purpose-built language for money. A platform client withdraws $250,000 from @users:8452:available to @platform:custody:hot:withdrawals:pending before the funds move to an external self-custody address:
// SELF_CUSTODY_WITHDRAWAL_INITIATED
// Event: client 8452 initiates a 250,000 USDC withdrawal
send [USDC/6 250000000000] (
source = @users:8452:available
destination = @platform:custody:hot:withdrawals:pending
)
set_tx_meta("event_type", "self_custody_withdrawal_initiated")
set_tx_meta("withdrawal_id", "wdr001")
set_tx_meta("destination_address", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1")
The destination address rides as metadata because Ledger cannot enforce invariants on a balance it cannot see.
On finality, a second posting moves the funds to a boundary account and closes the pending state; on failure or drop, a compensating posting returns the funds to the client without altering the original entry.
Reconciliation then compares internal balances against on-chain state ingested through a direct on-chain connector, covering both the omnibus balance versus the sum of client balances and the pending-withdrawals accounts versus outstanding broadcasts.
At Formance, Ledger's account structure and postings are the authoritative source for custody-related transaction and balance state, with programmatic enforcement by the core ledger.
Four questions settle the architecture for self-custody wallets: signing authority, operational readiness, regulatory posture, and ledger representation.
Can any single compromise (one share, one key, one laptop, and one signing UI) produce a valid signature? Whatever answers yes is your real security boundary.
Do key ceremonies, share refresh, and disaster recovery exist as rehearsed runbooks, or as knowledge in two engineers' heads?
Does your status as a bank, broker-dealer, or EU CASP permit, or require, a specific custody arrangement? The fiat-to-digital asset playbook maps posture onto account structure.
Can your core ledger express every custody-related accounting state, pending, confirmed, failed, swept, as a posting today, or does that state live in side tables?
Formance Ledger is built for the fourth answer. You model the custody state with programmatically enforced double-entry, immutable, hash-chained entries, bi-temporality, and metadata for external context (such as destination addresses and broadcast attempts) within a core ledger.