Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt

Use this file to discover all available pages before exploring further.

This page has been updated for Wallets SDK V1. If you are using the previous version, see the previous version docs or the V1 migration guide.
Custody determines who holds the cryptographic keys that control a wallet. In traditional finance, custody is binary — either the institution holds the assets or the customer does. In blockchain-based systems, custody is more nuanced because key management, transaction authorization, and asset storage can be separated across multiple parties. Crossmint’s signer architecture gives you fine-grained control over custody. The signers you choose — and who holds them — define your custody model.

​
What Is Custody?

Custody, in the context of digital assets, refers to who has the ability to authorize transactions on a wallet. It is not about where the wallet “lives” (it lives onchain) but about who holds the keys that can move assets. The question is straightforward: can your organization unilaterally sign a transaction on this wallet?
  • If yes — the wallet is custodial. Your organization is the custodian.
  • If no, only the end user can — the wallet is non-custodial (also called self-custodial)
  • If both parties must cooperate, or different operations require different parties — the wallet uses a hybrid model

​
Why Custody Matters

Custody classification affects multiple dimensions of your product:
DimensionImpact
Regulatory complianceMany jurisdictions impose licensing requirements on custodial wallet providers. Non-custodial wallets generally face fewer regulatory obligations because the provider never controls user assets.
LiabilityA custodian is responsible for safeguarding assets. If a custodial wallet is compromised, the custodian may bear liability. Non-custodial providers shift this responsibility to the end user.
User trustSome users prefer self-custody for sovereignty and privacy. Others prefer custodial solutions for simplicity and recoverability. Your audience determines which model builds more trust.
Operational controlCustodial wallets let your organization enforce business rules — spending limits, approval workflows, compliance checks — at the signing layer. Non-custodial wallets delegate all authorization to the user.
RecoveryIn custodial models, your organization can recover access to a wallet using its server keys. In non-custodial models, recovery depends entirely on the user’s recovery signer (email OTP, phone OTP, or external wallet).

​
Custody Models in Crossmint

Crossmint does not impose a single custody model. Instead, your signer configuration determines custody. The three models below represent the most common patterns.

​
Non-Custodial (Self-Custodial)

In a non-custodial configuration, only the end user holds signing keys. Crossmint has no ability to authorize transactions or access the wallet’s assets. Typical signer configuration:
RoleSignerHeld by
SignerDevice signerUser’s device (secure enclave)
RecoveryEmail or phone OTPUser (via their email/phone)
The device signer is generated inside the user’s hardware security module. The private key never leaves the device and is not extractable — not by your application, not by Crossmint, and not by the device operating system. The recovery signer (email or phone OTP) is similarly controlled by the user. When to use:
  • Consumer applications where users expect self-sovereignty over their assets
  • Products where regulatory classification as a non-custodial provider is important
  • Applications where minimizing your organization’s liability for user assets is a priority

​
Custodial

In a custodial configuration, your organization holds all signing keys. You have full control over the wallet and can authorize transactions without user involvement. Typical signer configuration:
RoleSignerHeld by
SignerServer signer or Cloud KMSYour infrastructure
RecoveryServer signer or Cloud KMS (different key)Your infrastructure
Both signers are server-side keys held in your backend. The primary key handles day-to-day signing. The recovery key (using a different secret or KMS key) provides key rotation and disaster recovery capability. Organizations with existing cloud KMS infrastructure can use Cloud KMS signers for stronger key isolation. When to use:
  • Treasury, escrow, and operational wallets owned by your organization
  • Products where you need programmatic control over transaction approval (spending limits, compliance checks, multi-step workflows)
  • AI agent wallets where the agent is platform-hosted and acts on behalf of your organization
  • Scenarios where your organization is already a licensed custodian or plans to become one

​
Hybrid

Hybrid models distribute signing authority across multiple parties. Neither your organization nor the user can act unilaterally — both must participate in some capacity. Example signer configuration:
RoleSignerHeld by
SignerDevice signerUser’s device
Additional signerServer signerYour infrastructure
RecoveryExternal walletUser’s existing wallet
Hybrid configurations are useful when you need to enforce organizational policies (compliance, rate limiting, fraud detection) while preserving user sovereignty over their assets. The specific signer combination depends on which operations require user consent versus organizational approval. When to use:
  • Enterprise applications with compliance requirements that demand organizational oversight
  • Platforms that need to enforce transaction policies while giving users self-custody
  • Multi-signature workflows where different parties authorize different operations

​
Mapping Signers to Custody

The table below summarizes how common signer configurations map to custody models.
SignerRecovery signerCustody modelWho can sign transactions?
Device signerEmail/phone OTPNon-custodialUser only
Device signerServer signerHybridUser signs; organization recovers
Server signerServer signerCustodialOrganization only
Cloud KMSCloud KMS (different key)CustodialOrganization only
PasskeyEmail/phone OTPNon-custodialUser only
External walletServer signerHybridUser signs; organization recovers
Server signerEmail/phone OTPHybridOrganization signs; user recovers
Custody is not just about the signer. The recovery signer matters too — whoever controls recovery can add new signers to the wallet, which means they can eventually gain signing access. A wallet with a user-controlled signer but an organization-controlled recovery signer is a hybrid model, not non-custodial.

​
Compliance Considerations

Custody classification varies by jurisdiction and is subject to evolving regulation. The following are general considerations — not legal advice.
  • Non-custodial providers generally face fewer licensing requirements, but some jurisdictions are introducing regulations that apply to non-custodial wallet providers as well (for example, requirements around transaction monitoring or user identity verification).
  • Custodial providers in most jurisdictions need some form of financial services license (money transmitter license in the US, MiCA authorization in the EU, etc.). The specific requirements depend on the jurisdiction, the types of assets held, and the services offered.
  • Hybrid models are the most complex from a regulatory perspective. Classification depends on the specific signer configuration and the degree of control each party has.
Crossmint’s architecture gives you the flexibility to adjust your custody model as regulatory requirements evolve — you can add, remove, or change signers without migrating wallets or changing wallet addresses.

​
See Also

Signers

The full signer type reference and recommended configurations

Architecture

How the dual-layer architecture separates wallet logic from signer control