Custody Provider

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.

Managed signing requires a healthy configuration. New accounts also require that configuration to be enabled for account creation.

Custody provider is not custody approval: the provider signs, the approval decides whether a payload may be signed at all.

Why the custody provider mattersCopy Anchor Link

A custody provider lets an organization 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. Which provider backs an account changes who can sign. It never changes who owns the position.

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 organization submits.

Providers come in two kinds. A managed provider holds keys and signs when the platform asks. The managed family covers DFNS, Fireblocks, Luna HSM, Ripple custody, 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 signing integrations support EVM-compatible networks. A deployment also decides which of these providers it offers at all: every kind has a switch, custody.providers.<kind>.enabled, and Ripple custody is the one that ships off. While a provider is off it appears nowhere in the Console, no organization can store a new configuration for it, and the deployment refuses to boot if it names that provider as its own signer. Configurations stored before the switch moved keep signing, and their credentials can still be rotated.

Every provider kind the deployment offers is available when adding a configuration. What the deployment decides is narrower: whether platform credentials will work for that choice, since they resolve only for the provider this deployment's own signer is built for. An organization 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 afterward, so custody moves only when an administrator adds a new configuration and points new accounts at it.

Managed keys or the holder's own walletCopy Anchor Link

Choose managed custody for accounts the organization operates. Provider policy decides which signing requests can proceed automatically and which need approval. With an external provider, keys remain with that provider. Platform key storage keeps them within the deployment's trust boundary.

Choose a self-custody provider for holders who keep their own keys. The holder signs in person for every request, and no instruction from the platform can move their assets on its own. 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 external key, and identity verification does not restore key control, so a holder should add another active signer before access is lost.

Managed configurations carry one further choice: whose credentials reach the custodian. Platform credentials come from the deployment operator's own custodian relationship, so an organization can start signing before it has a custodian contract of its own. Organization credentials are supplied and rotated by the organization itself, against a custodian account it can audit independently, which puts the rotation duty where the audit obligation already sits.

Managing custody day to dayCopy Anchor Link

An organization owner or a platform administrator manages provider configurations from the Console's Custody screen, under organization settings. Each configuration shows as a card naming its provider, execution health, and whether it accepts new accounts, along with the latest quarantine or recovery 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.

How rotation replaces a credentialCopy Anchor Link

A custody credential never changes in place. Rotation stages a replacement and runs it through a probe gate before anything currently signing is touched.

Rotation runs for one configuration at a time. A per-configuration lock serializes concurrent rotation requests, so a second request waits for the first to finish rather than racing it; if the first holds the lock past 30 seconds, the second times out and fails instead of waiting indefinitely. The probe itself is bounded at the same 30 seconds, so a provider that stops answering fails the rotation rather than hanging it.

The commit updates the credential version and the rotation timestamp together. Signing picks up the new credential from that moment; the platform detects the version change and rebuilds its connection to the provider, with no restart involved. 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 doCopy Anchor Link

A custody provider configuration is always in one of three health states: healthy, unhealthy, or quarantined. A healthy managed configuration can sign, and it appears in the account-creation catalog only when new accounts are enabled. Unhealthy and quarantined configurations do neither: managed signing refuses them, and new accounts cannot select them.

Healthy and unhealthy track the probes. A failed probe marks the configuration unhealthy, stopping it from signing or opening new accounts, 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 on the platform beyond running Probe again once the fault clears there. Quarantine is the third state, and it does not follow that automation: only an administrator can enter or leave it.

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 just as deliberate: 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 contractCopy Anchor Link

On the API, custody is a catalog of provider configurations scoped to the caller's organization. The GET /custody/provider-configurations route serves the account-creation listing. Every other operation, list, create, probe, enable, disable, quarantine, recover, rotate, and delete, runs under the admin provider configuration endpoints, restricted to an organization owner or a platform administrator.

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 read anywhere returns a credential.

Some refusals carry a distinct id worth handling by name; others collapse into one. A probe failure answers DALP-12006 and is retryable. A delete against a configuration that accounts still reference answers DALP-12009 rather than cascading. Recovering without a probe that passed since the quarantine began answers DALP-12005. Quarantine or recovery with an empty reason answers DALP-12008. A request that would change a configuration's provider or credential source, and a rotation that repeats a current or older credential version, both answer the same DALP-12004. Treat them as one case in your own error handling, since the wire gives no way to tell them apart. The error catalog lists the full set.

Controls and evidenceCopy Anchor Link

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.

Immutability is enforced at the record, before anything reaches a provider, rather than at the custodian. The answer to which signer was authoritative for an account, and when, therefore has exactly one source: the configuration's own history.

Frequently asked questionsCopy Anchor Link