Multi-signer wallets recipe

Overview

This page walks the multi-signer non-custodial flow as it works in sandbox: a customer claims non-custodial control, the roster reaches its signing quorum, deposit addresses become available, and a payout collects a stamp from each required signer before broadcasting. The same six webhook topics fire in live — the only sandbox-specific behavior is auto-activation (described under Sandbox vs live caveats).

Pick your roster to match the signing mode

The roster shape you claim with depends on the customer’s signing mode, which Conduit sets per organization. Send the wrong shape and the claim is rejected.

A new sandbox organization defaults to programmatic_unattended. The mode limits api_key members only; passkeys count toward signingThreshold in every mode, so an all-passkey roster is valid too. programmatic_unattended (the sandbox default) permits api_key admins, so the shortest path is a machine-signer roster — at least two api_key admins, each carrying a compressed publicKey (P-256 by default, or a secp256k1 key with signatureScheme: "secp256k1" / "secp256k1_eip191"), with signingThreshold reached by those keys. (The stricter programmatic mode rejects api_key admins with 422 SIGNING_MODE_ROSTER_INVALID: there the machine members take role: "signer" and admins are passkeys.)

curl -X POST "https://api.sandbox.conduit.financial/v2/customers/${CUSTOMER_ID}/wallets/claim-non-custodial" \
  -H "x-api-key: ${SANDBOX_API_KEY}" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "roster": [
      { "email": "ada@example.com",   "name": "Ada",   "role": "admin", "credentialType": "api_key",
        "publicKey": "026ba6ae01069237c022ce00bd8a72878f9e279e8fd4303e1c34f9176ccbc38252" },
      { "email": "grace@example.com", "name": "Grace", "role": "admin", "credentialType": "api_key",
        "publicKey": "02866e9d07d1c2dce9aecb9faf05614c5a673c21b9b529c33d3bda3bade93e0224" }
    ],
    "signingThreshold": 2,
    "chains": ["ethereum", "polygon"]
  }'

Machine members need no enrollment — there is no wallet_signer.invited / wallet_signer.enrolled cycle (steps 2–5 below). The claim returns status: "provisioning", and activation then completes on its own and claim.completed fires; await that webhook (or poll GET /v2/customers/:id/wallets until each chain is active) before using the wallets. You then sign each payout with a machine stamp at POST /v2/signing-requests/:id/approve; the full generate-key-and-stamp loop is in Machine-signer stamping. The customer’s mode surfaces publicly as signingMode on the transaction.awaiting_signature webhook.The 6-step passkey recipe below works in every signing mode. It is the only recipe for a customer set to passkey_required (Conduit sets this; older organizations default to it), because that mode refuses any api_key member.

Prerequisites

The customer must be KYB-approved (customer.activated fired).
Your organization has a webhook endpoint registered and reachable. The whole flow is webhook-driven; without an endpoint you will never see step 2 onward.

Before you claim: activate the CRYPTO_WALLET feature

claim-non-custodial requires an approved CRYPTO_WALLET feature on the customer. The pattern is:

# 1. Activate crypto for the customer
curl -X POST "https://api.sandbox.conduit.financial/v2/customers/${CUSTOMER_ID}/features" \
  -H "x-api-key: ${SANDBOX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "type": "crypto_wallet" }'

In sandbox the default is auto-approve: the response carries status: "approved" and you can claim immediately. To rehearse the live review path, drive the application terminal yourself:

# Force a manual-review outcome on a pending CRYPTO_WALLET application
curl -X POST "https://api.sandbox.conduit.financial/v2/sandbox/applications/${APPLICATION_ID}/simulate/decision" \
  -H "x-api-key: ${SANDBOX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "approved" }'

Calling claim-non-custodial before the feature is approved returns 422 CRYPTO_FEATURE_NOT_APPROVED. Calling it from a country on Conduit’s crypto-restricted list returns 422 CRYPTO_NOT_AVAILABLE_IN_JURISDICTION at the feature-application step (the claim never runs).

The 6-step recipe

This recipe is the passkey path — each signer enrols a passkey and stamps on the verify page. It works in every signing mode. For a programmatic_unattended customer (the sandbox default), the machine-signer roster above is the shorter path: sign via Machine-signer stamping; that roster needs no enrollment (its wallets activate on their own after the claim — await claim.completed), so steps 2–5 do not apply.

Claim non-custodial control

POST /v2/customers/:customerId/wallets/claim-non-custodial with a roster, a signing threshold, and an optional chains array. Omit chains to provision a wallet on the default set of supported chains in one claim; pass it to choose the chains, including ones outside the default set such as solana (see Crypto Wallets). The customer must have an approved CRYPTO_WALLET feature (see above).

curl -X POST "https://api.sandbox.conduit.financial/v2/customers/cus_034A0gCCVsxdV2PjHLx9k1/wallets/claim-non-custodial" \
  -H "x-api-key: ${SANDBOX_API_KEY}" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "roster": [
      { "email": "ada@example.com",   "name": "Ada",   "role": "admin",  "credentialType": "passkey" },
      { "email": "grace@example.com", "name": "Grace", "role": "admin",  "credentialType": "passkey" },
      { "email": "ken@example.com",   "name": "Ken",   "role": "signer", "credentialType": "passkey" }
    ],
    "signingThreshold": 2,
    "chains": ["ethereum", "polygon"]
  }'

Returns 202 Accepted:

{
  "claimId": "wcc_2xKjF9mQb7vN4hL1pR3w8t",
  "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
  "status": "provisioning",
  "rosterSize": 3,
  "signingThreshold": 2,
  "estimatedActivationCompletionMinutes": null
}

Roster validation runs before any side effects: roster size ≥ 2, admin count ≥ 2, threshold ≥ 1 and ≤ roster size. See error codes for the full list of claim-time rejection reasons.

Receive one wallet_signer.invited webhook per roster member

Each invited signer gets their own webhook with a per-user verificationUrl. URLs are scoped to one signer and expire at expiresAt.

{
  "topic": "wallet_signer.invited",
  "data": {
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
    "walletSignerId": "wsg_2xKjF9mQb7vN4hL1pR3w8t",
    "email": "ada@example.com",
    "name": "Ada",
    "role": "admin",
    "credentialType": "passkey",
    "verificationUrl": "https://app.conduit.financial/verify/f7iKXgpCNdXOLh1ml4j5WXAuowNMIt5FXwyVr7TGNk0",
    "expiresAt": "2026-01-22T09:30:00.000Z"
  }
}

Distribute the verification URLs out-of-band

Send each signer their own verificationUrl through your product’s notification channel — email, Slack, in-app — whatever you use to reach end users. Conduit does not deliver these URLs to signers directly.Treat the URL like a magic-link credential: one signer, one URL, do not share across the roster.

Receive one wallet_signer.enrolled webhook per signer

When a signer opens their URL and completes enrollment, you receive:

{
  "topic": "wallet_signer.enrolled",
  "data": {
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
    "walletSignerId": "wsg_2xKjF9mQb7vN4hL1pR3w8t",
    "email": "ada@example.com",
    "role": "admin",
    "passkeyCount": 1
  }
}

Track these against the walletSignerIds you saw in step 2 to know when the last signer has enrolled.

Wallets become usable (sandbox auto-activation)

Once every roster member has enrolled, sandbox auto-activates the customer’s wallets and fires claim.completed, carrying the claimId and the activated walletIds:

{
  "topic": "claim.completed",
  "data": {
    "claimId": "wcc_2xKjF9mQb7vN4hL1pR3w8t",
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
    "walletIds": ["wlt_034A0gCCVs2WISC5kS1P58"]
  }
}

A customer-level crypto_wallet.completed (carrying customerId only, no wallet IDs) also fires. Deposit addresses are now available via GET /v2/customers/:customerId/wallets. The customer can receive funds and submit payouts.

Auto-activation is sandbox-only. In live, activation runs an additional ceremony — see Sandbox vs live caveats.

Submit a payout — stamps collect over webhook

POST /v2/payouts returns 202 { id: "txn_...", status: "pending" }. The payout is screened for compliance + Travel Rule before any signer is asked to sign, so a payout that fails screening is rejected before the roster ever sees it. Once screening clears the status flips to processing and the payout drives these event topics:1. transaction.processing — fires once when compliance + Travel Rule clear and the payout enters the signing queue. Progress signal only; it carries no verificationUrl, so do not route signers off this event.2. transaction.awaiting_signature — fires once when the payout parks at the cosign gate. In the passkey signing mode (shown here) the verificationUrl is a single shared approval page; the roster members signed-in there each stamp the payout with their passkey. A wallet in a programmatic signing mode carries a signingRequestId — plus an optional verificationUrl when its roster has an active passkey signer who may also approve on the verify page — see Machine-signer stamping.

{
  "topic": "transaction.awaiting_signature",
  "data": {
    "signingMode": "passkey_required",
    "transactionId": "txn_034A0gCCVmVhsfuR8SfVwM",
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
    "verificationUrl": "https://app.conduit.financial/verify/mtQzSU2hdy0DuZ6za2IHIoVDgXzshrFtN38kMULRDFw",
    "requiredApprovals": 2,
    "expiresAt": "2026-01-15T09:45:00.000Z",
    "attempt": 1
  }
}

3. transaction.signature_collected — fires once per signer stamp. Drive a progress UI off collected / required.

{
  "topic": "transaction.signature_collected",
  "data": {
    "transactionId": "txn_034A0gCCVmVhsfuR8SfVwM",
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
    "walletSignerId": "wsg_2xKjF9mQb7vN4hL1pR3w8t",
    "collected": 1,
    "required": 2
  }
}

4. transaction.quorum_met — fires once when collected >= required. Compliance already passed before signing; once quorum is met, Conduit casts its final compliance approval to complete the transfer — applying the screening result already on file, not re-screening after signing.

{
  "topic": "transaction.quorum_met",
  "data": {
    "transactionId": "txn_034A0gCCVmVhsfuR8SfVwM",
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1"
  }
}

5. transaction.completed (or transaction.failed) — fires once when the payout reaches a terminal state. In sandbox it fires after the payout reaches real testnet finality, which takes minutes. transaction.failed carries a failureCode your integration branches on — see Failure cases.

How compliance works in sandbox. Compliance + Travel Rule screening runs before the signers are asked to sign; in sandbox it auto-passes, so the payout flips to processing and reaches the co-signing gate immediately. Once the signers reach the configured threshold, the sandbox casts Conduit’s final compliance approval and the payout broadcasts on the testnet. In live, the pre-signing screening runs the real sanctions + travel-rule checks; after quorum Conduit casts its final compliance approval to complete the transfer, applying the screening result already on file rather than re-screening.

Failure cases

A payout that does not complete fires transaction.failed with one of the codes below.

`failureCode`	Meaning	Retryable?
`user_signature_declined`	A signer rejected the payout from the approval page.	Yes — submit a new payout.
`user_signature_timeout`	The signing window expired before quorum was reached.	Yes — submit a new payout.
`user_signature_rejected_by_provider`	A signer’s passkey approval could not be accepted.	Yes — submit a new payout. Contact support on repeat.
`roster_changed`	A signer was removed (or moved out of the signing pool) mid-flight. Their stamp was scrubbed and the payout could not finish on the new roster.	Yes — re-initiate; the new attempt collects from the current roster.
`compliance_review_rejected`	Compliance screening rejected the payout before signing, so it never reached the signers. No funds moved.	No — contact support.
`provider_rejected`	The chain broadcast was rejected by the upstream RPC, or a sandbox scenario forced a reject. `failureMessage` carries the reason when surfaced.	Yes after adjusting inputs (destination, amount, rail).

See the error reference for the full catalog and resolution playbooks.

Roster lifecycle ceremonies

Once the 6-step recipe above ships a working multi-signer wallet, three lifecycle ceremonies on the roster itself become testable. All three are sandbox-runnable; the underlying root-quorum ceremony is identical to production.

Add a fourth signer mid-life

POST /v2/customers/{customerId}/wallet-signers provisions a new signer on an active roster. The threshold is unchanged; only the eligible-stamper pool grows.

# Step 1 — add the fourth signer
curl -X POST 'https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers' \
  -H "x-api-key: $SANDBOX_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "dave@example.com",
    "role": "signer",
    "credentialType": "passkey"
  }'
# Response: signer row in pending_activation. `wallet_signer.invited` + `wallet_signer.added` fire.

# Step 2 — the new signer opens the `verificationUrl` from `wallet_signer.invited`
# and registers a passkey on their device. `wallet_signer.enrolled` fires.

# Step 3 — subsequent payouts collect stamps from any 2 of the 4 active signers.
# (Threshold stays at 2; only the eligible-stamper pool grew.)

Expected webhooks:

wallet_signer.invited (new signer; payload carries verificationUrl)
wallet_signer.added (co-emitted)
wallet_signer.enrolled (after the signer registers a passkey)

To also raise the threshold (e.g. to require 3 of 4), call the customer-quorum endpoint after the new signer is enrolled. See Signing thresholds.

Promote a signer into the root quorum (seat swap)

POST /v2/customers/{customerId}/wallet-signers/{signerId}/promote seats a signer (or a non-root admin) in the root quorum; .../demote unseats a root admin. Each call runs a root-quorum ceremony in the background. The root quorum holds a fixed two customer seats. When both are filled — as they are on the two-admin roster from the recipe above — promoting a new admin into it is a seat swap: the promote call names the current root admin to unseat via demoteSignerId, and one ceremony does both.

# Promote signer Ken into the root quorum, unseating Grace in the same ceremony.
# demoteSignerId is required here because both root seats are filled.
curl -X POST 'https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerKenId}/promote' \
  -H "x-api-key: $SANDBOX_API_KEY" -H "idempotency-key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ "demoteSignerId": "{signerGraceId}" }'
# 202 Accepted. `wallet_signer.promoted` (Ken) and `wallet_signer.demoted` (Grace)
# fire when the ceremony completes (typically a few seconds). The root quorum still
# holds two customer seats — now Ada and Ken; Grace reverts to a signer.

# Demote an admin back to signer (only valid while the roster keeps >= 2 admins).
curl -X POST 'https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerAdaId}/demote' \
  -H "x-api-key: $SANDBOX_API_KEY" -H "idempotency-key: $(uuidgen)"
# 202 Accepted. `wallet_signer.demoted` fires on completion.

Constraints:

Promoting without demoteSignerId while both root seats are filled returns 409 ROOT_AT_CAPACITY_SWAP_REQUIRED. Retry with a demoteSignerId.
demoteSignerId must name a current root-quorum admin, else 409 DEMOTE_TARGET_NOT_IN_ROOT.
A swap that would leave fewer than 2 admins on the roster returns 409 SWAP_WOULD_BREAK_F12.
Running a second promote/demote before the first ceremony completes returns 409 CEREMONY_IN_FLIGHT. Retry after a short backoff.
Demoting an admin that would drop the admin count below the floor returns 409 WOULD_BREAK_MIN_ADMINS (at the default two root seats, demoting either root admin hits this).

Parked ceremony approvals

Some roster changes park awaiting an existing admin’s approval before the ceremony runs: the wallet_ceremony.awaiting_admin_approval webhook fires carrying the admin link in its adminVerificationUrl field (webhook payloads have no urlAudience field — that field belongs to the POST /wallet-signers response). An admin opens that link and approves with their passkey, in sandbox and in production. The parked ceremony then resumes; a decline rejects it.

Ghost-vote scrubbing: signer removed mid-payout

DELETE /v2/customers/{customerId}/wallet-signers/{signerId} removes a signer. It returns 204 No Content; the removal outcome is disclosed additively in the response headers — X-Conduit-Ceremony-Status (pending_removal while the roster-remove ceremony awaits admin approval, or removed once fully removed) and X-Conduit-Ceremony-Id (the ceremony id; omitted once terminally removed). Retrying the same DELETE is idempotent. If the signer had already stamped an in-flight payout, the stamp is scrubbed from every affected payout. Payouts that can no longer reach quorum on the new roster terminate failed with failureCode: "roster_changed".

# Assume the customer has root admins A and B with a 2-of-2 quorum,
# and an in-flight payout where A has already stamped (1 of 2 collected).

# Step 1 — seat swap: promote a new admin D into the root quorum and unseat A in
# the same ceremony, so the roster keeps two root admins throughout. Then remove A
# (now a non-root signer). Each ceremony is sequential per customer.
curl -X POST 'https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerDId}/promote' \
  -H "x-api-key: $SANDBOX_API_KEY" -H "idempotency-key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ "demoteSignerId": "{signerAId}" }'
# Wait for `wallet_signer.promoted` (D) and `wallet_signer.demoted` (A) before the next call.

curl -X DELETE 'https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerAId}' \
  -H "x-api-key: $SANDBOX_API_KEY" -H "idempotency-key: $(uuidgen)"
# `wallet_signer.removed` fires. Signer A's stamp is scrubbed from the in-flight payout.

Expected webhook order:

wallet_signer.promoted (signer D, seated into the root quorum)
wallet_signer.demoted (signer A, unseated by the same swap)
wallet_signer.removed (signer A)
transaction.signature_collected (collected: 0) — re-fires after the scrub
transaction.failed with failureCode: "roster_changed" — payout cannot reach quorum on the new roster

Client recovery: re-submit the payout. The new attempt collects stamps from the current roster. See ghost-vote scrubbing for the underlying model.

Sandbox vs live caveats

Signing and broadcast are real in sandbox. A passkey_required wallet signs with a real passkey, a programmatic wallet signs with a machine stamp at POST /v2/signing-requests/:id/approve, and the payout broadcasts a real txHash you can open on the explorer. A wallet provisioned before real testnet was enabled cannot transact (422 LEGACY_MOCK_WALLET_UNSUPPORTED). See Use a real testnet and Machine-signer stamping.

Every webhook topic and payload on this page is identical between sandbox and live. The differences below are operational, not contractual.

Multi-signer wallets run in production, and the recipe on this page is the recipe you integrate against there. A passkey signer enrolls and approves with a real device-bound passkey in sandbox and in live, so that path needs a person at a device. A machine-signer roster runs without one.

Wallet activation is automatic in sandbox, manual in live. When the last signer enrolls in sandbox, crypto_wallet.completed fires immediately. In live, activation runs an additional governance ceremony before the wallet becomes usable.
Roster and enrollment ceremonies can wait for an admin approval. In production, adding a signer, removing a signer and attaching a passkey each need one business-admin stamp, so the call answers 202 Accepted with a ceremony id and an admin verification URL. Promotion, demotion and signing-quorum changes wait for an approval in sandbox too. When a ceremony parks, an admin opens adminVerificationUrl and approves with their passkey.
Chain finality is real. After quorum_met, the payout broadcasts on a real testnet and transaction.completed fires at finality, which takes minutes. Its txHash resolves on the network’s explorer.

What changes in live

The contract you integrate against is the same. The pieces underneath swap out:

The real compliance pipeline (sanctions screening + travel rule) replaces the auto-pass stamp. Some payouts will be rejected here that always passed in sandbox.
A real activation ceremony replaces the sandbox auto-activate hook. crypto_wallet.completed does not fire the instant the last signer enrolls.
The per-(wallet, chain) signing queue runs the same in sandbox as in live: a queued payout carries a positive queuePosition on GET /v2/payouts/:id and on the transaction.queue_position_changed webhook in both.

Sandbox-only levers

POST /v2/sandbox/customers/:customerId/simulate-reset-claim tears down the customer’s wallet setup so a claim can be re-run. A production wallet claim is not reversible. The signing and enrollment levers (wallet-signers/:signerId/mark-enrolled, payouts/:id/simulate-stamp, payouts/:id/simulate/cosign, orders/:id/simulate/cosign, verifications/:token/simulate/ceremony-stamp, customers/:customerId/wallet-ceremonies/simulate-approval-gate) return 409 SANDBOX_SIGNING_SIMULATION_UNAVAILABLE on the sandbox. Enroll and approve with a real passkey, or use a machine-signer roster.

Get started

Transaction guides

References

Scenario libraries

Multi-signer wallets recipe

Overview

Pick your roster to match the signing mode

Prerequisites

Before you claim: activate the CRYPTO_WALLET feature

The 6-step recipe

Failure cases

Roster lifecycle ceremonies

Add a fourth signer mid-life

Promote a signer into the root quorum (seat swap)

Parked ceremony approvals

Ghost-vote scrubbing: signer removed mid-payout

Sandbox vs live caveats

What changes in live

Sandbox-only levers

See also

​Overview

​Pick your roster to match the signing mode

​Prerequisites

​Before you claim: activate the CRYPTO_WALLET feature

​The 6-step recipe

​Failure cases

​Roster lifecycle ceremonies

​Add a fourth signer mid-life

​Promote a signer into the root quorum (seat swap)

​Parked ceremony approvals

​Ghost-vote scrubbing: signer removed mid-payout

​Sandbox vs live caveats

​What changes in live

​Sandbox-only levers

​See also

Overview

Pick your roster to match the signing mode

Prerequisites

Before you claim: activate the CRYPTO_WALLET feature

The 6-step recipe

Failure cases

Roster lifecycle ceremonies

Add a fourth signer mid-life

Promote a signer into the root quorum (seat swap)

Parked ceremony approvals

Ghost-vote scrubbing: signer removed mid-payout

Sandbox vs live caveats

What changes in live

Sandbox-only levers

See also