A provider configuration resolves who signs, a managed provider or the holder's own wallet, and custody approval separately authorises the payload.
A configuration's provider and credential source are fixed at creation. Credentials change through probed rotation, and every new or rotated credential must pass a live probe against the provider before the platform commits it. A different provider is a new configuration.
New accounts require a healthy configuration that is enabled for account creation. An unhealthy configuration still signs some requests, and only a quarantined configuration signs nothing.
A custody provider signs. Custody approval decides whether a payload may be signed at all.
Why the custody provider matters
A custody provider lets an organisation decide who holds the key that signs for its accounts. That key sits with a managed custodian that signs under its own policy, or with the account holder's own wallet, where the holder signs and the platform never touches the key. That choice sits underneath every privileged operation an account performs across an asset's lifecycle: a subscription, a corporate action, a trade delivery. Each one confirms through signer verification at the moment of signing, whatever the bound provider requires. The provider decides who can sign for the account's address, and the position stays with that address on chain.
Every account is created against one provider configuration, a stored record naming the provider, the networks it serves, and whose credentials it uses. That record decides who controls the keys behind every transaction the organisation submits.
Providers come in two kinds. A managed provider holds keys and signs when the platform asks. The managed family covers IBM Digital Asset Haven, DFNS, Fireblocks, Luna HSM, Ripple custody, Utila, and the platform key store, which keeps keys in the platform's own secret store. A self-custody provider hands signing to the account holder instead. Privy, Dynamic, and browser wallets connect a wallet the holder controls, and the platform never holds that key. These integrations sign on EVM-compatible networks.
A deployment decides which of these providers it offers at all. Every kind has a switch, custody., and Ripple custody and Utila are the two that ship off. While a provider is off:
- The Console form does not offer it, and no organisation can store a new configuration for it.
- It is never offered for new accounts.
- The deployment refuses to boot if it names that provider as its own signer.
Configurations stored before the switch moved keep signing, still appear in the Console's provider list, and their credentials can still be rotated.
Every provider kind the deployment offers is available when adding a configuration. A configuration keeps the name of the provider it was added as, so the Console and the Investor portal show IBM Digital Asset Haven for a configuration added as IBM Digital Asset Haven and for every account it holds. An organisation can run several configurations side by side, and each account keeps the configuration it was created with. A configuration's provider and credential source cannot change afterwards, so custody moves only when an administrator adds a new configuration and points new accounts at it.
Managed keys or the holder's own wallet
Choose managed custody for accounts the organisation operates. Provider policy decides which signing requests can proceed automatically and which need approval. With an external provider, keys stay with that provider. With the platform key store, keys sit in the deployment's own secret store, so whoever operates the deployment holds them.
Choose a self-custody provider for holders who keep their own keys. The holder's wallet signs every request the platform sends to it, so the platform cannot sign a transfer in the holder's name. Two controls still act without the holder's signature. A holder of the custodian role on an asset can force a transfer or recover tokens from a lost wallet, and on a single-owner Smart Wallet the platform guardian can name a replacement owner key, which takes effect 72 hours later unless the holder cancels it. The account is proven by an interactive signature from the holder's wallet, and later signing requests require the holder's interaction. The cost is recoverability. The platform cannot restore a lost key for a plain wallet, and identity verification does not restore key control there, so a holder should add another active signer before access is lost.
One participant, the platform's single record for a person or an organisation, can use both kinds of custody. A participant has at most one on-chain identity on each network. It can own several wallets and bind each wallet to that identity on a network. On one network a managed key and a wallet the holder controls can therefore belong to the same participant and the same identity.
The Console marks an owned wallet with no binding as “Held, not bound”. On the participant's page, “Add wallet” either creates a managed key or connects a wallet the participant already controls. When the key behind the participant's identity is in self custody, the participant has to sign the identity installation on each new network itself. The “Install identity on this chain” action then stops and shows “The participant's key is in self custody, so the participant must sign on this chain itself.”
Managed configurations carry one further choice: whose credentials reach the custodian. Platform credentials belong to the deployment operator, the team that runs the platform installation. The Console offers them for the platform key store only, so a configuration added there for any other managed provider uses organisation credentials. The organisation supplies and rotates those itself, against a custodian account it can audit independently. That puts the rotation duty where the audit obligation already sits.
Managing custody day to day
An organisation owner or a platform administrator manages provider configurations from the Console's Custody screen, under organisation settings. Each configuration shows as a card naming its provider, execution health, and whether it accepts new accounts, along with its latest audit event. The same screen adds a configuration, which the platform records only once a live probe against the provider succeeds. It also controls account creation separately from execution: disabling new accounts stops only new signups, and existing accounts keep signing through it. For a managed configuration, the same screen rotates its credentials. Quarantining or recovering execution requires a written reason that lands in the audit trail.
An owner can extend a managed configuration's EVM network coverage from its card. The platform checks the required signing lanes, keeps all existing networks, and leaves adding the network to the organisation as a separate action.
Which network a DFNS wallet is created on
A DFNS wallet lives on one DFNS network, and the platform picks it when it creates the wallet. It takes the first of three values that exists: the network the request names, the DFNS network that matches the request's chain ID, then the default network. The default network is the configuration's “Default network” field when it is set, then DFNS_DEFAULT_NETWORK, then Ethereum. The chain ID match covers 16 networks: Ethereum, Polygon, Arbitrum One, Optimism, Base, BSC, Avalanche C and Celo, each with its testnet. A network outside that list gets the default network, and on it DFNS signs wallet transactions as sign-only.
How the platform names provider wallets
A provider console lists wallets by name, so the platform names each wallet it creates at a managed provider DALP <role> <organization name> <chain ID> <reference>. The role says what the wallet does, such as participant for an investor's wallet, bundler or organization-identity. The reference is eight hexadecimal characters derived from the wallet's account in the platform, so two wallets of one organisation on one network almost never share a name. A name never carries a person's name or user identifier.
The organisation name is written in plain ASCII characters. Accents are dropped, so Northwind Café reads Northwind Cafe, and every other character outside plain ASCII, such as an Arabic letter or an emoji, becomes ?. A name holds at most 100 characters, and a Ripple Custody alias at most 75, so the platform shortens a long organisation name to fit. The role, the chain ID and the reference always stay whole.
“Reconcile wallet roles” renames each wallet on DFNS, Fireblocks and Ripple Custody that still carries a name the platform chose. The new name follows the wallet's current role and the organisation's current name, and keeps the wallet's reference.
On Ripple Custody it also rewrites the account description and the dalpKind property for the role. Each rename there is an account intent described as Rename account <old alias> to <new alias>, or as Update the description of account <alias> when only the description changes. The intent carries the organisation and the dalpKind of the wallet's role, the same properties as the account's creation, so your Ripple policies approve it the same way. A name that a person gave the wallet stays, unless it follows a pattern the platform or the provider uses for its own names, such as Wallet 3.
How each provider signs and withdraws a request
Each provider declares how it signs on each network, and whether the platform can withdraw a request that the provider still holds. A wallet transaction comes from an ordinary key-held wallet, and a user operation comes from a Smart Wallet. “Provider files them” means the provider submits the signed request to the network itself. “Sign-only” means the provider returns a signature and the platform submits the request. Custody approval describes how long a request can wait for a decision before the platform withdraws it.
A Fireblocks workspace that lists no blockchain with a network's chain ID, or whose native asset Fireblocks has retired, has no lane there, and the platform refuses to add that network to the configuration. When a provider cannot withdraw, the platform records that the request is still open at the provider, with the provider's reference, so an operator can reject it in the provider's own console.
DFNS, Fireblocks, Ripple Custody and Utila hold a request for an approver and show text that DALP writes from the request, and all of them read one text. Fireblocks and Utila show it as the note on the request. Ripple Custody shows it as the intent description, which holds at most 250 characters and opens with a 60-character summary of the action when the text is longer. DFNS has no note, so it shows a label of at most 39 characters inside the 50-character external id of the request. The label keeps the operation, the amount, the token symbol and the counterparty. A text longer than 24 characters, such as a long token name, shows only its start, with no mark. When the label is still too long, it leaves out whole parts or cuts one, and it marks that cut with ~.
How rotation replaces a credential
A custody credential is not edited in place. Rotation stages a replacement and runs it through a probe gate before anything signing is touched.
A candidate credential becomes active only after a live probe succeeds, and a failed probe leaves the current credential signing.
Each rotation advances the credential version by exactly one. When two rotations of the same configuration run at once, both probe their candidate, the first to commit becomes version n + 1, and the second is refused with a conflict because a newer version is already recorded. Read the configuration before you retry. The probe is bounded at 30 seconds, so a provider that stops answering fails the rotation instead of hanging it.
Each rotation writes the new credential to a new slot in the platform's secret store. The commit updates the credential version, the slot and the rotation timestamp together. Signing reads the credential from the new slot from that moment, with no restart involved. The platform keeps the previous slot and tries to remove older ones after a one-hour grace period. A slot it fails to remove stays until a later attempt removes it. A rotation on a quarantined configuration passes through the same gate and can succeed, but it does not restore execution. Recovery is its own step with its own evidence.
Health states decide what a configuration may do
A custody provider configuration is always in one of three health states: healthy, unhealthy, or quarantined. A healthy configuration appears in the account-creation catalogue when new accounts are enabled. Unhealthy and quarantined configurations never appear there, so new accounts cannot select them. A quarantined configuration also signs nothing: every request bound to it fails and is never sent to another provider.
Probes move a configuration between healthy and unhealthy, administrators quarantine and recover it, and only a healthy configuration opens accounts.
A failed probe marks the configuration unhealthy, which takes it out of account creation, and a later passing probe restores it, with no administrator involved in either direction. The fix runs on the provider's own side: the probe reaches the live provider, so there is nothing to reset in the platform beyond running Test connection again once the fault clears there.
Unhealthy does not stop every signature. A transaction request from a custody account refuses an unhealthy configuration, and so do the on-chain calls the platform signs with the organisation's own submission signer. Other signatures still go through an unhealthy configuration, such as a managed co-signature on a multisig wallet proposal or a typed-data signature. To stop every signature through a configuration, quarantine it. Only an administrator can enter or leave quarantine.
An administrator quarantines a configuration with a written reason, and the state sticks: passing probes are recorded but change nothing, and a successful credential rotation does not clear it either. Recovery is deliberate too: it refuses to run unless a probe has passed since the quarantine began, and it records its own reason, so the audit trail shows who stopped execution, why, who restored it, and on what evidence.
The integration contract
On the API, custody is a catalogue of provider configurations scoped to the caller's organisation. The GET /api/ route serves the account-creation listing. GET /api/ returns the options the organisation offers its investors. Every other operation runs under the admin provider configuration endpoints, restricted to an organisation owner or a platform administrator: list, create, probe, update, quarantine and recover, rotate, reconcile wallet roles, record a legacy provider wallet on its provisioning claim, and delete. An update turns new accounts on or off, offers the configuration to investors, makes it the investor default, or adds a network.
Two read surfaces exist for two audiences. The account-creation listing returns only healthy configurations enabled for new accounts, with credential provenance and execution diagnostics excluded, because a caller opening an account needs capabilities and nothing more. The administrator listing adds provenance, health, and the latest audit event, and still returns no secret material. No custody API route or Console screen returns a stored credential.
The account-creation listing also filters configurations by network. Send chainId to name the network. With no parameter, the listing uses the request's chain. An invitee reading with invitationId instead defaults to the inviting organisation's chain when available, falling back to the request's chain. Select the network before offering a configuration: participant creation refuses a configuration that does not serve the requested chain.
Several refusals on these routes share one code, and the error message names the case.
A quarantine or a recovery without a reason fails request validation, because the reason is required and cannot be empty. The error catalogue lists every code.
Utila webhooks
A Utila approval that waits for an approver is also woken by Utila itself. In the Utila Console, open Vault Settings, then Webhooks, and register https:// for transaction state changes. The platform checks the x-utila-signature header against the public key Utila publishes. That key is the default, so a stock install needs no setting. To use another key, set UTILA_WEBHOOK_PUBLIC_KEY to the PEM block or its base64 body. A blank value makes the platform answer every Utila delivery with 503 until a key is set.
A delivery only prompts a check: the platform reads the transaction from Utila again and decides from that answer, so a replayed or stale delivery cannot approve anything. A delivery with a bad signature is refused with 401. An event the platform has already handled is dropped.
Controls and evidence
For a control function, a custody credential is a secret the platform holds but never shows. Credentials live in the platform's secret store, keyed to one configuration and one credential version, and no Console screen or API response returns them. The platform reads them server-side only, to sign and to probe.
Evidence accumulates on the configuration itself. Every rotation stamps a rotation time and a strictly increasing credential version, so an auditor can reconstruct when each credential took over without an external change log. Every quarantine and every recovery writes an audit event naming what was done, who did it, the written reason, and when. A recovery event also records the passing probe that justified it.
The platform enforces a configuration's fixed provider and credential source on the record, before anything reaches a provider. For a key-held wallet, the configuration's history records which provider configuration signed for an account and when, and the custodian's own log records what it signed. For a Smart Wallet, the on-chain owner or signer set, with its change history, records which key the account accepted.
Frequently asked questions
Can an administrator quarantine a configuration while a rotation is running?
Yes. Quarantine and rotation are separate writes, and a rotation probes its candidate before it writes anything, so a quarantine can complete while a rotation is still probing. Both changes remain in force: if the rotation goes on to succeed, the new credential becomes active, but the configuration is already quarantined and stays stopped, like any other rotation on a quarantined configuration.
Does the health state mean anything for a self-custody provider?
Not in the same way. A live probe only exists for managed providers. A self-custody configuration has no server-side credential to test, so its probe passes automatically and it stays Healthy by default. Quarantine still applies the same way: an administrator can quarantine a self-custody configuration with a recorded reason, which removes it from the account-creation catalogue exactly as it would a managed configuration.
Can a self-custody provider's credentials be rotated the same way?
No. A self-custody provider has no platform-held credential to rotate, since the holder's own wallet signs and the platform never stores a key for it. A rotation request against a self-custody configuration is refused with 409 CUSTODY_PROVIDER_CONFIG_CONFLICT, code DALP-12272, because only a managed configuration stores a credential the platform can replace.