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, each signer enrolls a passkey, 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).

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.

Headless sandbox testing. The webhook-driven flow above assumes signers complete enrollment + payout approval through the verification portal. Two sandbox-only shortcut endpoints let you script the whole loop without a browser.

Every /v2/sandbox/* endpoint on this page is sandbox-only and does not transfer to production. Each one stands in for a person acting at a browser. Production exposes no counterpart, so a flow that only ever ran through these levers has not exercised the production step it replaced. The table under What changes in live names the production path for each.

POST /v2/sandbox/wallet-signers/:signerId/mark-enrolled — marks a signer enrolled with no WebAuthn credential at all. Auto-activation fires once every roster member is marked. Stands in for the production passkey ceremony, where the signer opens verificationUrl and registers a real device-bound passkey.
POST /v2/sandbox/payouts/:payoutId/simulate-stamp — stamps a payout on behalf of a signer. Stands in for the production approval page, where the signer authorizes the payout with the passkey they enrolled.

// 1. Claim non-custodial control
const { claimId } = await api.post(`/v2/customers/${customerId}/wallets/claim-non-custodial`, {...});

// 2. Mark each signer enrolled (skips the portal entirely)
for (const signer of webhookSignersInvited) {
  await api.post(`/v2/sandbox/wallet-signers/${signer.walletSignerId}/mark-enrolled`);
}
// → crypto_wallet.completed fires once all enrolled

// 3. Submit a payout, then stamp it from the sandbox endpoint
const { id: payoutId } = await api.post('/v2/payouts', {...});
for (const signer of admins.slice(0, signingThreshold)) {
  await api.post(`/v2/sandbox/payouts/${payoutId}/simulate-stamp`, { walletSignerId: signer.id, outcome: 'approved' });
}
// → transaction.completed fires (compliance auto-stamps inside the sandbox)

These endpoints exist in sandbox only — they have no live counterpart.

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

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 the chain-confirm autopilot resolves this within ~5 seconds of quorum_met. 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, so transaction.quorum_met is followed within milliseconds by transaction.completed. 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 — enroll the new signer (sandbox bypasses the real passkey UX)
curl -X POST 'https://api.sandbox.conduit.financial/v2/sandbox/wallet-signers/{newSignerId}/mark-enrolled' \
  -H "x-api-key: $SANDBOX_API_KEY" -H "idempotency-key: $(uuidgen)"
# `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 mark-enrolled)

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). In production an admin opens that link and approves with their passkey. In sandbox, stamp it headlessly using the verification token from that URL. This lever is sandbox-only and does not transfer to production; it stands in for that admin passkey approval:

curl -X POST 'https://api.sandbox.conduit.financial/v2/sandbox/verifications/{token}/simulate/ceremony-stamp' \
  -H "x-api-key: $SANDBOX_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "outcome": "approved" }'
# 200 — the parked ceremony resumes. { "outcome": "declined" } rejects it instead.
# Replaying against an already-decided token returns the verification at its current state.

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

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. Provisioning, signer enrollment and wallet activation all execute against the real signing provider, so the recipe on this page is the recipe you integrate against in production. One step cannot be scripted: a production signer enrolls with a real device-bound passkey, which needs a person at a browser. The sandbox-only levers below stand in for that step and for the approvals a person casts.

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 wait for an admin approval in live. Adding a signer, removing a signer and attaching a passkey each run under a policy that needs one business-admin stamp in production, so the call answers 202 Accepted with a ceremony id and an admin verification URL. Sandbox applies them at once by default, because the stand-in signing provider has no policy engine. To rehearse the production path, turn the gate on per ceremony type and then stamp the ceremony:

# Make every later signer add on this customer wait for an admin approval, as production does.
curl -X POST "$SANDBOX/v2/sandbox/customers/$CUSTOMER_ID/wallet-ceremonies/simulate-approval-gate" \
  -H "Authorization: Bearer $SANDBOX_KEY" -H "Content-Type: application/json" \
  -d '{"target":"signer_add","requireApproval":true}'

Promotion, demotion and signing-quorum changes already wait for an approval in sandbox, so they need no gate.

Passkey enrollment uses synthetic credentials in sandbox. The sandbox verification flow goes through the same browser passkey UX as live — your test signers will see the same OS prompt — but the credentials it produces are sandbox-only and never authorize real funds.
Chain confirmation autopilots in sandbox. After quorum_met, sandbox resolves transaction.completed within ~5 seconds without a real chain broadcast. Live waits for real chain finality.
No sandbox payout ever touches a real chain. Destination addresses, hashes, and signatures in sandbox are isolated from mainnet. A txHash on a sandbox transaction.completed is shape-valid hex but not lookupable on-chain.

What changes in live

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

The real signing provider replaces the sandbox mock.
Real WebAuthn passkeys replace synthetic credentials. Signers must complete browser passkey enrollment.
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 queuePosition field on signing-queue webhooks is populated by the real per-(wallet, chain) counter in live; in sandbox it is omitted.

Sandbox-only levers and what each replaces

Every endpoint below is sandbox-only and does not transfer to production. Production has no counterpart route: the production column is the human step the lever stands in for.

Sandbox-only lever	What it does	The production path it stands in for
`POST /v2/sandbox/wallet-signers/:signerId/mark-enrolled`	Activates a signer with zero WebAuthn credential	The signer opens `verificationUrl` and registers a real device-bound passkey
`POST /v2/sandbox/payouts/:payoutId/simulate-stamp`	Stamps a payout for a signer	The signer approves the payout on the approval page with their passkey
`POST /v2/sandbox/payouts/:id/simulate/cosign`	Resolves the payout signing gate	The signing quorum stamps the payout, one signer at a time
`POST /v2/sandbox/verifications/:token/simulate/ceremony-stamp`	Approves or declines a parked ceremony	An admin opens `adminVerificationUrl` and approves with their passkey
`POST /v2/sandbox/customers/:customerId/wallet-ceremonies/simulate-approval-gate`	Turns the admin-approval gate on or off per change	Nothing — the gate is always on in production. The lever exists so a sandbox integration can reach it
`POST /v2/sandbox/customers/:customerId/simulate-reset-claim`	Tears down the customer’s wallet setup so a claim can be re-run	Nothing — a production wallet claim is not reversible

The passkey ceiling. A real passkey needs a real authenticator, so it cannot be driven from a test script. Automated tests use the levers above; verifying a genuine passkey is a manual browser step against sandbox. Plan for one manual pass per release of your signer-facing UI.

Get started

Transaction guides

References

Scenario libraries

Multi-signer wallets recipe

Overview

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 and what each replaces

See also

​Overview

​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 and what each replaces

​See also

Overview

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 and what each replaces

See also