Multi-signer wallets recipe

​

Overview

​

Pick your roster to match the signing mode

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"]
  }'

​

Individual customer: one admin

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": "passkey" }
    ],
    "signingThreshold": 1
  }'

​

Prerequisites

• The customer must be approved (application.approved and customer.created 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

​

The 6-step recipe

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": "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"]
  }'

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

{
  "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/sandbox/verify/f7iKXgpCNdXOLh1ml4j5WXAuowNMIt5FXwyVr7TGNk0",
    "expiresAt": "2026-01-22T09:30:00.000Z"
  }
}

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

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

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

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

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

​

Failure cases

​

Roster lifecycle ceremonies

​

Add a fourth signer mid-life

# Step 1 — add the fourth signer
curl -X POST "https://api.sandbox.conduit.financial/v2/customers/${CUSTOMER_ID}/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.)

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

​

Replace an admin with a signer

# Make signer Ken an admin in place of Grace, in one ceremony.
curl -X POST "https://api.sandbox.conduit.financial/v2/customers/${CUSTOMER_ID}/wallet-signers/${KEN_SIGNER_ID}/promote" \
  -H "x-api-key: $SANDBOX_API_KEY" -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{ \"demoteSignerId\": \"${GRACE_SIGNER_ID}\" }"
# 202 Accepted. `wallet_signer.promoted` (Ken) and `wallet_signer.demoted` (Grace)
# fire when the ceremony completes (typically a few seconds). The customer still
# has two admins — now Ada and Ken; Grace is a signer.

• Promoting without demoteSignerId returns 409 ROOT_AT_CAPACITY_SWAP_REQUIRED. Retry with a demoteSignerId.
• demoteSignerId must name one of the customer’s admins, else 409 DEMOTE_TARGET_NOT_IN_ROOT.
• Running a second promote before the first ceremony completes returns 409 CEREMONY_IN_FLIGHT. Retry after a short backoff.
• .../demote returns 409 WOULD_BREAK_MIN_ADMINS for every admin: replace the admin with a promote instead.

​

Parked ceremony approvals

​

Ghost-vote scrubbing: signer removed mid-payout

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

# Step 1 — replace A: promote signer D in place of A in one ceremony, so the
# customer keeps two admins throughout. Then remove A (now a signer).
# Each ceremony is sequential per customer.
curl -X POST "https://api.sandbox.conduit.financial/v2/customers/${CUSTOMER_ID}/wallet-signers/${SIGNER_D_ID}/promote" \
  -H "x-api-key: $SANDBOX_API_KEY" -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{ \"demoteSignerId\": \"${SIGNER_A_ID}\" }"
# 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/${CUSTOMER_ID}/wallet-signers/${SIGNER_A_ID}" \
  -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.

1. wallet_signer.promoted (signer D, now an admin)
2. wallet_signer.demoted (signer A, replaced in the same ceremony)
3. wallet_signer.removed (signer A)
4. transaction.signature_collected (collected: 0) — re-fires after the scrub
5. transaction.failed with failureCode: "roster_changed" — payout cannot reach quorum on the new roster

​

Sandbox vs live caveats

• 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 real compliance pipeline (sanctions screening + travel rule) replaces the scenario-suffix simulation. A payout with no suffix to trigger in sandbox can still be rejected here by real screening.
• 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

​

See also

• Multi-signer wallets — the conceptual mental model
• Withdrawals — full state diagram for the payout lifecycle
• Webhooks reference — every topic with full payload schema
• Error codes — failure-code resolution playbooks
• Sandbox overview